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 interrogate 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 paradigm.

Maven project

Unit tests

© Copyright 2012, Magnoni Luca. Created using Sphinx 1.1.3.