Loading... Loading ...
Notice: This documentation was generated by the free version of MireDot. As such, not all features are supported.
expand / collapse all

ICAT Restful API

ICAT provides both a SOAP and a RESTful web service to communicate with the core ICAT code which makes calls to a relational DBMS. This document describes the RESTful interface but assumes some knowledge of ICAT as explained in the ICAT user manual.

Error handling

In the case of an error from the ICAT code the returned json will be of the form: {"code":"BAD_PARAMETER", "message":"password too short", "offset":"0"} where the offset (which shows the offset to the entity which caused the error) will be omitted when it is not relevant. The status code will correspond to the type of the ICAT exception as shown by the code value. In the case of any other error, the code field will always be "INTERNAL", the offset will always be omitted and the status code will be 500 ("Internal Server Error"). Clients should always check the status code and if status/100 is not 2 then an error has occurred.

Testing

The @GET calls can be tried on a web browser and curl can be used to make any of the calls. For example a url of the form: https://example.com:443/icat/version will return some json such as {"version":"4.8.0"}

Getting started

The first thing you will need is a session so please see the documentation on POST to a session resource.

Import and export

The import and export calls make use of a special format to represent ICAT data efficiently. The file may contain line starting with a # sign. The first non-comment line contains the version number of the file format with major and minor parts. Each entity type is preceded by a blank line line followed by a one line entity descriptor and then a line for each entity of that type.

For example:

#  Version of file format
1.0

Facility ( name:0, daysUntilRelease:1, createId:2, createTime:3)
"Test port facility", 90, "Zorro", 1920-05-16T16:58:26.12Z

InvestigationType (facility(name:0), name:1)
"Test port facility", "atype"
"Test port facility", "btype"

Investigation(facility(name:0), name:1, visitId:2, type(facility(name:0), name:3), title:4)
"Test port facility", "expt1", "one", "atype", "a title"

The entity descriptor starts with the name of the entity type followed by a comma separated list attribute of field names held inside parentheses. It is not necessary to include those which you don't wish to set as any that are not present and are allowed to be null will be set to null when importing. So we see that this file will create a Facility with fields: name, daysUntilRelease, createId and createTime. Following the field name is a colon and an integer showing the offset to the data field in each of the next set of rows. So a facility will be created with a name of "Test port facility" and with 90 daysUntilRelease. All strings must be enclosed in double quotes; to represent a a double quote within the string then it must be escaped with a back slash: ". The following escape sequences are available:

  • t : tab
  • r : carriage return
  • f : form feed
  • b : bell
  • n : new line
  • " : "
  • ' : ' (Not really needed)
  • \ :

True, false and null literals are not case sensitive. The last two fields of the facility are createId and createTime. If you specify that you want all attributes and you are a "root user" then the values of createId and createTime will be respected otherwise the current time is used and the id is that of the user doing the import. Timestamp literals follow ISO 8601 and support fractional seconds and time zones. If the time zone is omitted it is interpreted as local time.

Now consider the InvestigationType for which we need to specify the facility to which it belongs and its name. The facility cannot be described by its id because we don't know what it is. So instead we list in parentheses the field names that define it. So name:0 is the name of the facility and name:1 is the name of the InvestigationType.

The next line shows the convenience of this syntax. The investigation has a facility (identified by its name:0) and the name:1 of the investigation and the visitId but it also has a type which is identified a facility (identified by its name:0) and by the name:3 of the type. Finally it has a title:4 field. Note that name:0 is used twice as in this case the investigation belongs to the same facility as its type. This works fine as long as we deal with entity types which have key fields. This is shown in the next snippet from an import file:

DataCollection(?:0)
"a"
"b"
"c"

DataCollectionDatafile(datafile(dataset(investigation(facility(name:0), name:1, visitId:2), name:3), name:4), dataCollection(?:5))
"Test port facility", "expt1", "one", "ds1", "df1",  "a"
"Test port facility", "expt1", "one", "ds1", "df2",  "b"

Job(application(facility(name:0), name:1, version:2), inputDataCollection(?:3), outputDataCollection(?:4))
"Test port facility", "aprog", "1.2.3", "a", "b"

Here we have the DataCollection which we imagine to be identified by the anonymous variable "?". This section of the file will create three DataCollection entries which we shall remember for the duration of the import process as "a", "b" and "c".

DataCollectionDatafiles are then associated with DataCollections "a" and "b" and a job is created with one DataCollection as input and one as output.

When performing export the same format is used however some values will be repeated - for example the facility name will appear many times in most rows.

  • Deprecated.

    Deprecated:

    {{baseUrl.value || ' '}}
       {{role}}{{$last ? '' : ', '}}

    Body

    Accept:
    no type

    Returns
    Content-Type:
    no type

    Response Headers

    Status codes

  • Interfaces not documented

    MireDot believes that the Java methods below correspond to REST interfaces, but somehow had problems parsing/processing these interfaces and therefore excluded them from the generated documentation. We would very much appreciate it if you would send us the interfaces (not the implementations) and the types used (returntype, parameters). This will allow us to further improve MireDot and better document your interfaces in the future.

Below is a list of potential problems detected by MireDot. They can be severe or not. Some of them wil result in low quality documentation, some are real implementation issues. With each warning, the Java method causing the problem is documented.

    • method:

    not shown here because this documentation was generated by the free version of MireDot. As such, not all features are supported.