SMIR REST API v0.12.1

Introduction

Security, Authentication, and Authorization

Productive releases of the SMIR REST API are only available using HTTPS.

Clients can authenticate themselves either by providing a user name and password using basic authentication, a JSON Web Token (JWT) or by providing a SAML token using brokered authentication.

Supplying Basic Authentication Headers

If you need to you may construct and send basic authentication headers yourself. To do this you need to perform the following steps:

1. Build a string of the form username:password
2. Base64 (RFC 4648) encode the string.
3. Supply an "Authorization" header with content "Basic " followed by the encoded string. For example, the string "demo@virtualskeleton.ch:demo" encodes to "ZGVtb0B2aXJ0dWFsc2tlbGV0b24uY2g6ZGVtbw==" in base64, so you would add the following to the request.

Authorization: Basic ZGVtb0B2aXJ0dWFsc2tlbGV0b24uY2g6ZGVtbw==

Supplying JSON Web Token (JWT) Authentication Headers

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

1. Use the Basic Authentication Headers approach described above in order to receive a JWT by visiting the API endpoint: /tokens/jwt
2. Supply an "Authorization" header with content "Bearer " followed by the JWT. The structure of a JSON Web Token (JWT) Authentication Header is listed below.

There are 3 parts separated by a . and each section is created differently which are header, payload and signature.

Authorization: Bearer aaaaaaaaaa.bbbbbbbbbbb.cccccccccccc

Supplying SAML Authentication Headers

If you need to you may construct and send SAML authentication headers yourself. To do this you need to perform the following steps:

1. Get the SAML token from the Identity Provider.
2. ZLIB (RFC 1950) compress the retrieved SAML token.
3. Base64 (RFC 4648) encode the compressed SAML token.
4. Supply an "Authorization" header with content "SAML auth=" followed by the encoded string.

Authorization: SAML auth=<Base 64 encoded compressed SAML token>

Requests, Responses, and Errors

A successful completion of a request returns one of three possible states:

200 OK

The default state. On GET requests, the response contains all the requested objects. On PUT and POST requests, the requested updates have been done correctly on the persistence layer.

201 Created

Returned on successful POST requests when one or more new objects have been created. The response contains information on the newly created objects, e.g. identification values.

204 No Content

Returned on successful DELETE requests.

An unsuccessful completion of a request returns one of:

400 Bad Request

The format of the URL and/or of values in the parameter list is not valid. Or the URL indicates a non-existing action.

401 Unauthorized

Either the request does not contain required authentication information or the authenticated used is not authorized to get a requested object or to do the request updated operation.

404 Not Found

The URL is correct, but the requested object does not (or no longer) exist.

405 Method Not Allowed

Different action methods may be restricted to one or more of the HTTP methods (GET, PUT, or POST). The received request uses one that is not allowed with the action method specified in the URL. In this case, other parts of the URL are not validated.

500 Internal Server Error

When a method causes an exception that has no adequate handling in the method itself. Developers of client systems are kindly requested to report these response states to the developing team of the SMIR and to transmit information about the respective request and the response objects.

501 Not Implemented

May occur during development. The requested action has been specified and documented, but not yet implemented.

HTTP method definitions

Method	Description	Attribute
GET	Getting a resource.	idempotent
POST	Creating a resource.	not idempotent
PUT	Updating a resource.	idempotent
DELETE	Deleting a resource.	idempotent
OPTIONS	Querying a resource.	idempotent

An idempotent HTTP method can be called many times without different outcomes.

General definitions

Pagination

All URLs returning a list of items with a GET request are paginated by default.

Option	Value type	Default value	Description
rpp	int	25	Defines the amount of included results per page.
			Allowed values: 10, 25, 50, 100, 250, 500
page	int	0	Defines the current page index.
			Allowed values: 0, 1, 2, ...

OData

OData v4, short for Open Data Protocol, is an open protocol (ISO/IEC approved and OASIS standard) to allow the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way. Endpoints having a model with a property annotated with the Filterable attribute support OData syntax.

For example the groups endpoint can be filtered by the name (property names have to start with a uppercase letter): groups?$filter=contains(Name,'sicas')

• Supported query options = $filter
• Supported functions = StartsWith + Contains
• Supported arithmetic operators = none
• Supported logical operators = all

Upload

An example request to upload a file with the multipart/form-data MIME type is listed consecutively.

Limitation: Exactly one file can be uploaded per request.

POST https://smir.ch/api/upload HTTP/1.1
Content-Type: multipart/form-data; boundary="09335213-878a-416b-b469-35551259de44"
Content-Length: 161300

--09335213-878a-416b-b469-35551259de44
Content-Disposition: form-data; filename=sample.dcm

"content of sample.dcm"

--09335213-878a-416b-b469-35551259de44--

Chunked Upload

The chunked upload endpoint can be used in order to upload large files. Chunks can be any size up to 100 MB. A typical chunk is 4 MB. Using large chunks will mean fewer calls and faster overall throughput. However, whenever a transfer is interrupted, you will have to resume at the beginning of the last chunk, so it is often safer to use smaller chunks.

1. Send a POST request equivalent to the one described above to https://smir.ch/api/chunked_upload?chunk=1&uid=b4e089e8-7403-4683-bad5-e64b2265bf4d for the first chunk.
2. Repeatedly POST subsequent chunks by incrementing the number in the URL identifying the current chunk.
3. After the last chunk, POST to https://smir.ch/api/chunked_upload/commit?filename=sample.dcm&uid=b4e089e8-7403-4683-bad5-e64b2265bf4d to complete the upload.

Date format

All dates are in UTC (Universal Time Coordinated) and represented in ISO 8601 format (International Organization for Standardization). Example:

2014-04-17T07:52:41.4700000Z

URL definitions

Remark: All SMIR REST API request URLs start with the /api/ prefix.

Versioning

Versioning will be applied once the version 1.0 is published. The version will be embedded within the URL. Example:

https://smir.ch/api/v1/...

The following lists which types of changes necessitate a new version and which don't:

Changes that don't require a new version:

• New resources
• New HTTP methods on existing resources
• New data formats
• New attributes or elements on existing data types

Changes that require a new version:

• Removed or renamed URLs
• Removed or renamed attributes or elements on existing data types
• Removal of support for HTTP methods on existing URLs

History

v0.11.0 01.12.2019

Breaking changes: the model representing files has been changed

• Before
  • Id is an integer
  • Objects navigation property is a paginated array
• Now
  • Id is a string (GUID)
  • Objects navigation property has been removed

Breaking changes: the files endpoints have been removed

• Removed endpoints
  • GET files/{id}?include={include}
  • GET files/{id}/download
  • GET files/{id}/objects?rpp={rpp}&page={page}
• Added endpoints
  • GET objects/{id}/files/{file_id}?include={include}
  • GET objects/{id}/files/{file_id}/download

v0.10.0 17.10.2018

Breaking changes: the model representing folders has been changed

• Before
  • ChildFolders is an array containing all direct child folders
• Now
  • ChildFolders is now paginated
  • GET folders/{id}/folders?rpp={rpp}&page={page}&include={include}

v0.9.0 25.09.2018

• group-users endpoints introduced for group management purposes (add/delete users to/from groups)
  • enables to filter groups of current user with OData (e.g. $filter=User/Id eq 123)
  • GET group-users?rpp={rpp}&page={page}&include={include}
  • GET group-users/{id}?include={include}
  • POST group-users
  • DELETE group-users/{id}

Breaking changes: the object-ontologies endpoints are now streamlined to match the others

• Before
  • GET object-ontologies/{type}/{id}
  • POST object-ontologies/{type}
  • PUT object-ontologies/{type}/{id}
• Now
  • GET object-ontologies/{id}
  • POST object-ontologies
  • PUT object-ontologies

v0.8.0 12.09.2018

Breaking changes: the model representing folders has been changed

• Before
  • ContainedObjects is an array containing all objects
  • Objects can be added or removed in this array

• Now

  • ContainedObjects is now paginated and objects can't be added or removed in this list anymore
  • ContainedObjectRelations property added​
  • GET folders/{id}/objects?rpp={rpp}&page={page}
  • GET folders/{id}/folder-objects?rpp={rpp}&page={page}

• folder-objects endpoints introduced

  • GET folder-objects/{id}
  • POST folder-objects
  • DELETE folder-objects/{id}