miredot.intro.html

<h1>ICAT Restful API</h1>

<p>
	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 <a href="../user.html">ICAT user manual</a>.
</p>

<h2>Error handling</h2>
<p>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.</p>

<h2>Testing</h2>
<p>
	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:
	<kbd> https://example.com:443/icat/version</kbd>
	will return some json such as
	<samp>{"version":"4.8.0"}</samp>
</p>

<h2>Getting started</h2>
<p>The first thing you will need is a session so please see the
	documentation on POST to a session resource.</p>

<h2>Import and export</h2>
<p>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.</p>
<p>For example:</p>
<pre>
#  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"
</pre>
<p>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:</p>
<ul>
	<li>\t : tab</li>
	<li>\r : carriage return</li>
	<li>\f : form feed</li>
	<li>\b : bell</li>
	<li>\n : new line</li>
	<li>\" : "</li>
	<li>\' : ' (Not really needed)</li>
	<li>\\ : \</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>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:</p>

<pre>
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"
</pre>

<p>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".</p>
<p>DataCollectionDatafiles are then associated with DataCollections
	"a" and "b" and a job is created with one DataCollection as input and
	one as output.</p>
<p>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.</p>