ELISA REST server

Documentation v3.0

EliSA API is a REST interface, which means it uses HTTP request to interact with the logbook messages.

You can use the REST API to create, reply, update or search elog entries.

You can use any language or tool that supports HTTP calls to access the EliSA REST API.

Functionalities

NEW!! REST API for new ELisA server changed URL format. Use /host.name.domain/elisa/api/ instead of /host.name.domain/elisa.api/api/

NEW in v3.0! You can use the REST API to interogate standalone logbooks other than ATLAS. You need to specify the logbook name in the URL as shown in the example below. If the logbook name is not specified in the URL, ATLAS is used by default.

Resource URL GET PUT POST DELETE
https://pc-atd-elisa-2.cern.ch/elisa.api/api/ATLOG_TEST/messages/1146

For NEW ELisA change URL format https://pc-atd-elisa.cern.ch/elisa/api/TEST/messages/57

Retrieve the message with ID 1146 from ATLOG_TEST logbook Not Used Reply to the message with ID 1146 from ATLOG_TEST logbook Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/messages/133603 Retrieve the message with ID = 133603 (default: the ATLAS logbook) Not Used Reply to the message with ID 133603 Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/messages/133603/body Retrieve the text body of the message with ID = 133603 Append the input text to the body of the message with ID = 133603 Not Used Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/messages/133603/attachments Retrieve the list of attachements for the message with ID = 133603 Not Used Create a new attachment for the message with ID =133603 Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/messages/112233/attachments/1 Retrieve the attachment 1 of the message with ID = 133603 Not Used Not Used Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/messages?[optional query parameters] Return the last 100 messages matching query criteria, if any Not Used [MISSING OPTIONS] Create a new message with ID automatically generated by Elisa Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/sa Return the list of possible system affected Not Used Not Used Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/mt Return the list of possible message types Not Used Not Used Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/mt/Shift%20Summary/sa Return the suggested list of system affected per the specified message type Not Used Not Used Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/mt/Online/opt Return the list of attributes for the Online message type Not Used Not Used Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/mt/Trigger/opt/Trigger_Area Return the details [name, type, possible values if any] for the specified option, including all the existing inner options Not Used Not Used Not Used
https://pc-atd-elisa-2.cern.ch/elisa.api/api/mt/Trigger/opt/Trigger_Area/Trigger%20Group Return the details of the specified inner option Not Used Not Used Not Used

Why PUT and POST

This difference comes from the HTTP specification (https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html). In particular, PUT (as GET and DELETE) is defined as an idempotent methods. That means no matter how many times the client call the method the result should always be the same. For the message creation, this means we could implement message creation with PUT but the disadvantage is that the client should provide the unique ID of the message, to implement idempotent behaviour.POST, that is not idempotent, allows to create a resource taking representation send by the client leaving out the resource identifier, generated by the server.

To be fully HTTP compliant (and idempotent) the message text update operation should ask for a representation of the entire new message body as input parameter.

Query Parameter

Name Type Required Default Description
limit Number   100 Number of entries returned
page Number     Page number for results pagination
username String     filter results per username
author String     filter results per author
systems_affected String     Comma separated list of system affected to filter messages on
message_type String     Filter per message type
from date (will be in UTC, now in format ‘26-JUL-12 12:00’)     initial search date
to date (will be in UTC, now in format ‘26-JUL-12 12:00’)     end search date
subject String     filter results by subject (SQL LIKE approach, partial matches allowed)
month_interval number   3 specify the number of month to limit the search. At the moment is implemented as URL paramter.
text String     search entries by text body. Search should be limited in time as it can be time consuming.
[NOT YET IMPLEMENTED] order String     specify an attribute used to order results
runNumber String     Search entries by DQSummary.RunNumber attribute; This search applies only to DQSummary message type.

Examples

Get last 100 messages:

https://atlasop.cern.ch/elisa.api/api/messages

Get last 100 messages from ATLOG_TEST logbook:

https://pc-atd-elisa-2.cern.ch/elisa.api/api/ATLOG_TEST/messages

Retrieve a single message:

https://atlasop.cern.ch/elisa.api/api/messages/112233

in XML (for programmatic usage, better to specify the Accept HTTP request header to the desired MIME type (i.e. application/xml):

https://atlasop.cern.ch/elisa.api/api/messages/112233.xml

in JSON (for programmatic usage, better to specify the Accept HTTP request header to the desired MIME type (i.e. application/json):

https://atlasop.cern.ch/elisa.api/api/messages/112233.json

Result limit and pagination:

https://atlasop.cern.ch/elisa.api/api/messages?limit=10&page=2

Filter messages by author:

https://atlasop.cern.ch/elisa.api/api/messages?limit=10&subject=Summary&author=Alina+Corso+Radu

Filter messages by author last month:

https://atlasop.cern.ch/elisa.api/api/messages?limit=10&subject=Summary&author=Alina+Corso+Radu&month_interval=1

Filter messages by text in the last month:

https://atlasop.cern.ch/elisa.api/api/messages?text=Stable+Beams&month_interval=1

Search DQSummary messages for RunNumber=1234 in the last two months:

https://atlasop.cern.ch/elisa.api/api/messages?runNumber=1234&month_interval=2

Insert new message (without user credentials)

curl -X POST -d '<input_message><body>This is the message text</body><message><systems_affected><count>1</count><system_affected>Pixel</system_affected></systems_affected><subject>Another command line test</subject></input_message>' https://pc-atd-elisa-2.cern.ch/elisa.api/api/messages -H "Content-Type:application/xml" -H "Accept: application/xml"

To specify SSO credential via curl have a look to the CERN SSO tool: https://linux.web.cern.ch/linux/docs/cernssocookie.shtml

Error Handling

If an error occurs, RESTful practices expect that we set an HTTP status code in the response to generally classify why the request failed. It is considered best practice by most REST API designers to re-use the status codes in the HTTP specification whenever possible, since so many existing HTTP clients understand most of these error conditions already and re-use encourages consistent behavior, which is always good for development.

https:/www.stormpath.com/blog/spring-mvc-rest-exception-handling-best-practices-part-1

Define a custom code dictionary like : https://www.twilio.com/docs/errors/reference

Error handling

This is an error report in XML. For example, the query:

curl -X GET http://localhost:8080/elisa.api/api/messages/wrongurl -H "Accept:application/xml"

return the following XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <error_report>
     <error>
       <entry key="status">NOT_FOUND</entry>
       <entry key="code">404</entry>
       <entry key="message">There is no resource for path /elisa.api/api/messages/wrongurl</entry>
       <entry key="developerMessage">There is no resource for path /elisa.api/api/messages/wrongurl</entry>
       <entry key="moreInfoUrl">mailto:luca.magnoni@cern.ch</entry>
     </error>
  </error_report>

Error result in JSON

This is an error report in JSON. For example, the query:

curl -X GET http://localhost:8080/elisa.api/api/messages/wrongurl -H "Accept:application/json"

return the following JSON document:

{"error":
  {"status":"NOT_FOUND",
  "code":"404",
  "message":"There is no resource for path /elisa.api/api/messages/wrongurl",
  "developerMessage":"There is no resource for path /elisa.api/api/messages/wrongurl",
  "moreInfoUrl":"mailto:luca.magnoni@cern.ch"}
}

Data validation

JSR 303 and Hibernate Validator have been some awesome additions to the Java ecosystem, giving you a standard way to validate your domain model across application layers. Combined with the annotations of the Java Persistence API (JPA) you have some very nice tools at your disposal to ensure that only valid data enters your database.

Developer hit

This has been implemented using Spring Exception handling paradgim.

Maven project

Unit tests