Introduction
This section will look at the ShareAspace REST APIs. The documentation starts with an introduction looking at the structuring of the APIs. To get a quick start and an easy understanding of the APIs, this section will mainly work with example code both from PowerShell as well as C# code.
A full reference of all the API routes can be found in the API reference section.
Architecture
As described in the technical architecture under concepts. The API is hosted on all the ShareAspace host nodes. However a client will never directly communicate with the host nodes themselves. Instead all clients will be communicating with the gateway and load balancer.
The API is found on the gateway deployed with the ShareAspace web application.
The base route will be at {Host}/api/.
Example:
https://essevm347.es.eurostep.com/api/
Structure
The API is on the highest level divided up into two sections. One for
operating on the ShareAspace Collection level api/collection/, and
one operating on ShareAspace Space level api/space/.
Collection
As the name entitles, the Collection APIs manages the whole ShareAspace Collection. With these APIs it is possible to manage Space Templates, Space instances, the overall health of the Collection as well as User Profiles (on a collection level, i.e. non space specific user settings such as Display name, avatar etc.)
In order to access the collection level of the API the user connecting must be setup as a Collection Administrator during bootstrap of the Collection.
Space
The Space section will always operate within the context of one Space.
Therefore the base route for the Space APIs will be api/space/{id}
where id is the identifier of a specific space.
In order to access one or more spaces using the API the user accessing
the API must have a role on a Participant within that space. Depending
on the access rights given by such a Role. The user using the API will
have access to different API operations (GET, POST, PUT, DELETE).
Authentication and Authorization
ShareAspace uses JSON Web Tokens (JWT) or Personal Access Tokens for authorizing against the ShareAspace REST APIs. There are also some administrative APIs that make use of API keys.
When ShareAspace is setup with an external identity provider a client can use an OAuth 2.0 authorization flow in order to receive an Id token. If ShareAspace has a trust to the identity provider the id token can be exchanged for a ShareAspace JWT.
HAETOAS and Response message
The ShareAspace REST APIs has been designed to follow the HATEOAS (Hypermedia As The Engine Of Application State). This means that a client interacting with the REST API will be provided with hypermedia links based on the current users access (i.e. operations on a requested resource will be described in the response message).
For a more detail description of the GET response messages see SoftType GET C# Example
Http Headers
Authorization
As stated above, in order to communicate whit the ShareAspace APIs one
must have an access token. When working on the collection level each
Http Request must have the Base64 encoded string representation of the
token in the Authorization header.
Example:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc....
The token is a JWT (JSON Web Token) access token. The token is signed with a symmetric key using the HMAC SHA512 algorithm
Tip
The Base64 representation can be decoded. This can be helpful when verifying a token (e.g. checking what claims has been issued etc.). https://jwt.io/ provides an online tool for decoding the Base64 string.
SAs-InformationFilter
When operating on a Space within the Space section of the API one must
also have a Base64 encoded string representation of the ShareAspace
Information Filter. The Information Filter is a JSON object describing
how you want to look at the information in ShareAspace. This includes
the time, your current role, etc. In the examples later on we will look
at how to get the Information Filter from the APIs. The Http Request
Header key for the Information Filter is SAs-InformationFilter.
Example:
SAs-InformationFilter: eyJvd25lciI6IjE....
Etag
The purpose of Etag is to support caching of non SoftType data.
When performing GET requests on data other than SoftTypes there will be
an Etag response header.
When the HTTP client has caching turned on - the first time a resource is
requested via a GET the response status code will be 200 and the
resource data will be part of the response payload.
Example
ETag 39-D4-02-60-C7-3F-16-54-30-69-F3-F2-FE-39-E7-FE
By storing this Etag in the cache and providing the value on the following
GET requests of the same resource using the If-None-Match request header
the ShareAspace REST API will only return status code 200 and the data payload
of the resource has been updated. If not, the ShareAspace REST API will respond with
the 304 status code (and no response payload).
Read more about the caching mechanism here.
Read more about how to active the cache for the .Net HttpClient here.
SAs-UOIVersion
When performing PUT and PATCH requests to update objects in ShareAspace
the SAs-UOIVersion header must be set. When retrieving data via GET requests the
current version for that specific information object will be returned in the
response JSON payload.
Example, GET payload:
{
"href": "...",
"data": { ... },
"version": 1,
"links": [ ],
"schema": { ... }
}
The version will also be part of all data payloads on the property $version.
Example, GET payload:
{
"href": "...",
"data": {
...
"$version": 1,
...
},
"version": 1,
"links": [ ],
"schema": { ... }
}
When doing a PUT/PATCH the API will check the version in the SAs-UOIVersion
Header to verify that that the PUT/PATCH is performed on the latest system
version of the object. If there is a mismatch between the server version and the
value of the SAs-UOIVersion header, the system will return the status code 409.
Example, SAs-UOIVersion header:
SAs-UOIVersion: 1
Tip
When performing a POST, PATCH, or PUT the response header will always
contain the SAs-UOIVersion header. E.g. updating an instance using PUT
the new version of the instance will be provided in the response header.
X-Correlation-Id
The X-Correlation-Id is a request header that is unique for every request. e.g. ShareAspace web will auto generate a GUID that is put on each HTTP request. If the X-Correlation-Id is provided ShareAspace will use this id for all log messages related to the initiating request. If further actions are triggered by a request, like an event being triggered leading to a call to an external extension this same correlation id will be passed on to these extensions. The extensions can then use this same id while logging requests internally within the extension. The extensions can also use the correlation id when reporting back log information to ShareAspace. This way the full impact of a request can be traced in the ShareAspace logs.
Example, X-Correlation-Id request header:
X-Correlation-Id: 5bb3fb20-0f7b-11ee-b090-c9ad50416076
OpenAPI
This documentation contains REST API reference documentation generated from the static portion of the ShareAspace OpenAPI definitions. They are divided into three categories
- System APIs
- Collection APIs
- Space APIs
You can find them under REST API References.
As described earlier, the ShareAspace REST APIs on the Space level are dynamic as they are based on the template used for creating the Space. All the Open API definitions, both static and dynamic can be retrieved via the REST API itself. The resource routes for these definitions are detailed in the REST API Reference section.
Example: Getting the dynamic OpenAPI definitions for all configured SoftTypes can be done via
GET /space/{spaceId}/SoftType/dynamic/softtype.openApi
Status Codes
The following status codes are used by the ShareAspace REST API.
| Status Code | Description |
|---|---|
| 200 | GET request OK, data in the response body |
| 204 | No content |
| 201 | Resource created, Response header contains the Location header with the URI for the created resources as well as the SAs-UOIVersion header containing the resource version (not to confuse with the cache Etag). |
| 304 | Not modified. No changes has been made to the server resource since the resource was cached. I.e. the value of the Etag in the If-None-Match request header is matching the server Etag. |
| 401 | Unauthorized. Typically because you are not authorized (missing access token) |
| 403 | Forbidden. No access to requested resource. You might still be authorized but you have no access to this resource. |
| 404 | Resource not found. |
| 409 | SAs-UOIVersion for PUT/PATCH has a mismatch, i.e. The server version has a later version than what was given in the request header. |
| 412 | SAs-UOIVersion is missing. |
| 500 | Server error, detailed message in the response body. |
Learning More
The OpenAPI documentation is a good reference when using the REST APIs. Another way of learning how the APIs work is by using the dev tools of a browser while running the ShareAspace Web Application. The Web Application is only using the REST APIs for all its operations. By studying the requests made when using the Web Application one can find a guidance in how to use the APIs.