Service API

Introduction

Sesam provides a RESTful API for controlling the service and for working with the data in the datahub.

If you follow the Getting Started guide, the api will be served on the url you find on the management studio "settings" page under the "Connection url" heading. For a cloud instance it will typically be on the form "https://instance-guid.sesam.cloud/api".

All references to this URL in this document should be substituted with the real URL for your Sesam instance. The rest of this document will assume that the api can be found on this URL.

The API documentation is also self-hosted and can be explored using the Swagger user interface at "<host:port>/api/reference".

Most API calls will require you to authenticate using a JWT token .

When using the Sesam command line client you can get a token using its login command:

sesam login --server_base_url https://instance-guid.sesam.cloud/api

This will prompt you for your username and password, download a JWT token and store it locally. All subsequent sesam client commands will then use this token.

You can also use a commandline tool like curl or wget to explore the API. This will be the most useful approach if you are planning to communicate with Sesam using a script or a program.

When using curl to access the API url's directly, you will need to supply the JWT token for each HTTP request. Here's an example that creates an alias for curl that does this for you (remember to change the example URL to your real sesam instance URL):

# Create a text-file with the email and password you use to log in to Sesam:
echo "email=YOUR_EMAIL_ADDRESS&password=YOUR_PASSWORD" > cred.txt

# Download the authorization token for the specified email and password and store it in an environment variable:
export SESAM_AUTH_HEADER="Authorization: Bearer $(curl -d @cred.txt https://instance-guid.sesam.cloud/api/jwt)"

# Make an alias to run curl with the authorization token:
alias curlJWT='curl -H "$SESAM_AUTH_HEADER"'

You can then substitute curl with curlJWT in all calls to the API. The rest of this document assumes that you have created this alias.

Note that if you are communicating with the API using your own program or script, you must remember to set the HTTP header property "Authorization" to the string "Bearer " concatenated with the token you get from the command:

curl -d @cred.txt https://instance-guid.sesam.cloud/api/jwt

This was built-in to the shell script snippet we used to set up the culrJWT alias previously; the "cred.txt" file contains the text "email=YOUR_EMAIL_ADDRESS&password=YOUR_PASSWORD" without the quotes and substituted with your real username and password. For security reasons, remember to remove the cred.txt file after you have retrieved the JWT token.

The most important api urls are:

/api/pipes (i.e. https://instance-guid.sesam.cloud/api/pipes)

This returns a list of pipes. For an explanation of what a pipe is, read the Pipes concept definition.

/api/datasets (i.e. https://instance-guid.sesam.cloud/api/datasets)

This returns a list of datasets. (For an explanation of what a dataset is, read the Datasets concept definition).

For a full description of the /pipes and /datasets endpoint, read the "Pipes" and "Dataset" sections in the Instance API Reference.

Examples

In the following we will go through a few examples of what you can do with the api. As mentioned previously, we will use the curlJWT alias we created to interact with the api from the command line. If you are using MS Windows you can install for instance Cygwin in order to install and use the curl command (and create the curlJWT alias).

Get a list of all the pipes

With curl:

curlJWT https://instance-guid.sesam.cloud/api/pipes

Using the Sesam client (after first having done sesam login- see the start of this document):

sesam get-pipes --server_base_url https://instance-guid.sesam.cloud/api

Get information about one specified pipe

To only get one specific pipe, add the pipe's "_id" attribute to the pipes-url. To get the pipe with the _id "Northwind:Products", you would do this:

With curl:

curlJWT https://instance-guid.sesam.cloud/api/pipes/Northwind:Products

Using the Sesam client:

sesam get-pipe Northwind:Products --server_base_url https://instance-guid.sesam.cloud/api

Run operations on a pipe

A pipe typically has a number of operations that can be triggered via the api. These are listed in the pipeinfo["runtime"]["supported-operations"] attribute. A typical value looks like this:

"supported-operations": [
            "enable",
            "disable",
            "start",
            "stop"
        ]

These operations are triggered by sending a POST-request to the url /pipes/{pipeID}/pump. For example: to disable the "Northwind:Products" pipe you would do this:

With curl:

curlJWT --data operation=disable https://instance-guid.sesam.cloud/api/pipes/Northwind:Products/pump

Using the Sesam client:

sesam get-pipe Northwind:Products --server_base_url https://instance-guid.sesam.cloud/api

To manually start the pipe's pump, you would do this:

With curl:

curlJWT --data operation=start https://instance-guid.sesam.cloud/api/pipes/Northwind:Products/pump
sesam start-pump Northwind:Products --server_base_url https://instance-guid.sesam.cloud/api

To stop a running pump, you would do this:

With curl:

curlJWT --data operation=stop https://instance-guid.sesam.cloud/api/pipes/Northwind:Products/pump

Using the Sesam client:

sesam stop-pump Northwind:Products --server_base_url https://instance-guid.sesam.cloud/api

Get a list of all the datasets

With curl:

curlJWT https://instance-guid.sesam.cloud/api/datasets

Using the Sesam client:

sesam get-datasets --server_base_url https://instance-guid.sesam.cloud/api

Get information about one specific dataset

To only get one specific dataset, add the dataset's "_id" attribute to the dataset-url. To get the dataset with the _id "Northwind:Products", you would do this:

With curl:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products

Using the Sesam client:

sesam get-dataset Northwind:Products --server_base_url https://instance-guid.sesam.cloud/api

Get the content of the dataset

To see the entities in the dataset, add "/entities?limit=3" to the dataset's url, like this:

With curl:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products/entities?limit=3

The "limit" parameter limits the number of returned entities to a managable number. Without this parameter, all the entities in the dataset would be returned. Depending on the size of the dataset, that could take a while, so it is generally a good idea to include a "limit"-parameter.

Using the Sesam client:

sesam get-dataset-entities Northwind:Products --limit 3 --server_base_url https://instance-guid.sesam.cloud/api

Get the content of the dataset as SDShare

To see the entities in the dataset as a SDShare feed, add "/sdshare-fragments" to the dataset's url, like this:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products/sdshare-fragments

Parameters such as limit also apply to this URL.

The corresponding SDShare collection feed is available from:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products/sdshare-collection

This collection feed URL is usually the URL you need to supply in a SDShare client.

Note that for the conversion of the entities to RDF to work, the entities must either:

  1. be pre-processed to consists of full URIs for all properties (including the _id property)

or:

  1. be pre-processed to CURIEs form AND the dataset id need to be registered as en entry in the RDF registry with appropriate prefix settings and prefix rules.

See Working with RDF for more information on how to prepare your data for RDF output.

Note that the SDShare feeds are not available through the Sesam client.

Instance API Reference

GET /pipes

Returns a list of all the pipes

Status Codes
POST /pipes

Creates one or more pipes

Query Parameters
  • force (boolean) -- When this is set to "true" it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.
Status Codes
  • 200 OK -- An array containing the new pipes
GET /pipes/{pipe_id}

Returns the specified pipe

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
DELETE /pipes/{pipe_id}

Deletes the specified pipe

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
GET /pipes/{pipe_id}/config

Returns the configuration of the specified pipe

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
  • 200 OK -- The pipe configuration
PUT /pipes/{pipe_id}/config

Updates the configuration of the specified pipe

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • force (boolean) -- When this is set to "true" it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.
Status Codes
GET /pipes/{pipe_id}/entities

Returns the entities produced by the specified pipe

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
  • since (string) -- Specifies the minimum since-value.
  • stage (string) -- Can be set to 'source', 'before-transforms', 'after-transforms' or 'sink' (default). 'source' returns entities as they come out of the source. 'before-transforms' returns entities as they are fed into the first transform. 'after-transforms' return entities as they look after the last transform. 'sink' returns entities as they look as they enter the sink.
Status Codes
GET /pipes/{pipe_id}/generate-schema-definition

Returns info about the schema of the entities processed by the pipe

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • sample_size (integer) -- Specifies the number of entities to sample from the source
  • keys_only (boolean) -- Specifies if only the array of keys should returned, or the whole schema
Status Codes
GET /pipes/{pipe_id}/pump

Returns info about the pump of the specified pipe

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
POST /pipes/{pipe_id}/pump

Runs some operation on the pump. The operation is specified by the 'operation' form parameter in the request.

The following operations exists:

"start":

Starts a new run of the pump. A pump is typically run automatically at scheduled intervals, but with this operation a pump can be started manually.

"stop":

Stops the pump, if it is running. If the pump is not already running, this operation has no effect.

"enable":

Enables the pump. This means that the pump can be run automatically by the system (usually on some fixed schedule).

"disable":

Disables the pump. This means that the pump cannot be run automatically by the system. Note that it is still possible to start the pump manually with the "start"-operation.

"update-last-seen":

Updates the "last-seen" value of the pump. This is the value the pump uses to figure out at which point in the source-data it stopped at its last run. The format of the "last-seen" form parameter depends on the source-system. It could be a date, and it could be some opaque binary value.

To clear the "last-seen" value of the pump, set the "last-seen" form parameter to an empty string. This will make the pump behave as if it was running for the first time. This is useful in cases where one wants to reprocess the data from scratch for some reason.

"set-last-seen-to-end":

Updates the "last-seen" value of the pump such that the pump thinks that it has seen all the source-data. Not all source-types supports this operation. NOTE: Doing this may result in data-loss, since any unread entities in the source will not be read. But

it is sometimes useful during development and testing; for instance when one has a huge existing source-dataset, but only want to run the pipe against new entities.

"reset-tracking" (Experimental):

Resets the dependency tracking so that it will continue starting from the end of dependent datasets.

Note that tracking will continue from what is the end of the datasets at the point in time when the pump runs, not the time at which this call is made.

Note that dependency tracking will then be skipped for untracked offsets, causing the output to be potentially incorrect. Use this feature only during development, or when you intend to do a full sync soon after the reset.

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
GET /datasets

Returns a list of all the datasets

Status Codes
  • 200 OK -- An array of datasets
GET /datasets/{dataset_id}

Returns the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Status Codes
DELETE /datasets/{dataset_id}

Deletes the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Status Codes
POST /datasets/{dataset_id}

Performs some operation on the specified dataset. The operation to do is specified with the "operation" form parameter. Supported operations are "rollback-circuit-breaker" and "commit-circuit-breaker".

Parameters
  • dataset_id (string) -- The id of the dataset
Status Codes
GET /datasets/{dataset_id}/entities

Returns the entities in the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Query Parameters
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
  • since (integer) -- An opaque value that can be used to efficiently skip already seen entities.
  • history (boolean) -- If this is true (the default) all entities, including replaced ones, will be returned. If this is false, only the latest version of the entities will be returned
  • reverse (boolean) -- If this is false (the default) the entities will be returned from the start of the dataset log. If this is true, the entities will be returned from the end of the dataset log instead
  • deleted (boolean) -- If this is true (the default) the entities marked as deleted will also be returned from the dataset log. If this is false, the entities that are marked as deleted will not included in result. If you request the complete history the deletes will always be included.
  • populated (boolean) -- If this is true the response will be 404 if the dataset has not yet been populated. It is not enough for the dataset to have data, but the data that's there must reflect a complete view of the dataset's source. In other words; the dataset must be fully populated. In practice this means that the pipe that populates the dataset has not yet had a complete full run. Normally 404 is only returned when the dataset does not exist.
  • uncommited (boolean) -- If true then the response may include uncommitted entities. This is only relevant if the pipe that writes to the dataset have a circuit breaker enabled. Use this for debugging purposes only.
  • subset (string) -- EXPERIMENTAL: If specified then the specified subset expression will be used to retrive entities in the dataset via a secondary index. If the index does not exist, then 404 is returned.
Status Codes
OPTIONS /datasets/{dataset_id}/entities

Returns the OPTIONS with this endpoint

Parameters
  • dataset_id (string) -- The id of the dataset
Query Parameters
  • since (integer) -- An opaque value that can be used to efficiently skip already seen entities.
  • history (boolean) -- If this is true (the default) all entities, including replaced ones, will be returned. If this is false, only the latest version of the entities will be returned
  • reverse (boolean) -- If this is false (the default) the entities will be returned from the start of the dataset log. If this is true, the entities will be returned from the end of the dataset log instead
  • deleted (boolean) -- If this is true (the default) the entities marked as deleted will also be returned from the dataset log. If this is false, the entities that are marked as deleted will not included in result. If you request the complete history the deletes will always be included.
Status Codes
POST /datasets/{dataset_id}/entities

Puts the specified entities into the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Query Parameters
  • force (boolean) -- If 'false', then the hashes of the posted entity and the previous version will be compared before storing the entity. The entity will not be written to the dataset if the hashes are the same. If 'true', then the entity will always be written to the dataset. The default is 'false'.
Status Codes
GET /datasets/{dataset_id}/entities/{rest_of_path}

Deprecated. Use the /entity endpoint. Returns the specified entity in the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
  • rest_of_path (string) -- The id of the entity
Status Codes
GET /datasets/{dataset_id}/entity

Returns the specified entity in the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Query Parameters
  • entity_id (string) -- The id of the entity
Status Codes
GET /datasets/{dataset_id}/sdshare-collection

Returns a sdshare collection feed for the entities in the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Status Codes
GET /datasets/{dataset_id}/sdshare-fragments

Returns a sdshare fragments feed for the entities in the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Status Codes
GET /datasets/{dataset_id}/sdshare-fragments/{rest_of_path}

Returns a sdshare fragment for the specified entity in the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
  • rest_of_path (string) -- The id of the entity-id
Status Codes
GET /datasets/{dataset_id}/indexes

Returns the indexes on the specified dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Status Codes
  • 200 OK -- The indexes of the dataset.
GET /datasets/{dataset_id}/generate-schema-definition

Returns info about the schema of the entities in the dataset

Parameters
  • dataset_id (string) -- The id of the dataset
Query Parameters
  • sample_size (integer) -- Specifies the number of entities to sample from the dataset
  • keys_only (boolean) -- Specifies if only the array of keys should returned, or the whole schema
Status Codes
GET /config

Returns the entire configuration of the node as an array of json objects, or as a zip-archive, depending on the value of the 'Accepts' header.

Status Codes
PUT /config

Overwrites the entire configuration of the node.

Status Codes
GET /
Status Codes
POST /
Status Codes
GET /env

Returns the currently defined environment variable values.

Status Codes
POST /env

Adds a variable or list of variables to the environment variable manager. If a variable already exists, it is overwritten.

Status Codes
PUT /env

Adds a variable or list of variables to the environment variable manager. If a variable already exists, it is overwritten.

Status Codes
PATCH /env

Adds a variable or list of variables to the environment variable manager. If a variable already exists, it is overwritten.

Status Codes
DELETE /env/{env_var}

Deleted the specified environment variable.

Parameters
  • env_var (string) -- The name of the environment variable to delete
Status Codes
GET /secrets

Returns the names of the currently defined secrets.

Status Codes
PUT /secrets

Adds a secret or list of secrets to the secrets manager. If a secret already exists, it is overwritten.

Status Codes
POST /secrets

Adds a secret or list of secrets to the secrets manager. If a secret already exists, it is overwritten.

Status Codes
DELETE /secrets/{secret_key}

Deleted the specified secret.

Parameters
  • secret_key (string) -- The name of the secret to delete
Status Codes
GET /health

Sesam api health information

Status Codes
GET /license

Returns info about the current license

Status Codes
PUT /license

Upload a new license key. The new license will replace the old license if valid.

Status Codes
GET /metadata

Returns the service metadata

Status Codes
PUT /metadata

Updates the service metadata

Status Codes
DELETE /metadata

Deletes all service metadata

Status Codes
GET /publishers/{pipe_id}/sdshare-collection

publisher endpoint sdshare collection feed

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
GET /publishers/{pipe_id}/sdshare-fragments

publisher endpoint sdshare fragments feed

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
Status Codes
GET /publishers/{pipe_id}/entities

publisher endpoint json entities

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
Status Codes
GET /publishers/{pipe_id}/entities/{filename}

publisher endpoint json entities - filename in url version

Parameters
  • pipe_id (string) -- The id of the pipe
  • filename (string) -- The filename to use as attachment filename
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
Status Codes
GET /publishers/{pipe_id}/csv

publisher csv endpoint

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
  • linked_excel_file (string) -- Instead of returning a CSV file, return a Excel file with a "connection" link to the original CSV URL. This parameter contains the filename to use.
Status Codes
OPTIONS /publishers/{pipe_id}/csv/

publisher csv endpoint OPTIONS (for office)

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
GET /publishers/{pipe_id}/csv/{filename}

publisher csv endpoint - filename in url version

Parameters
  • pipe_id (string) -- The id of the pipe
  • filename (string) -- The filename to use as attachment filename
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
  • linked_excel_file (string) -- Instead of returning a CSV file, return a Excel file with a "connection" link to the original CSV URL. This parameter contains the filename to use.
Status Codes
GET /publishers/{pipe_id}/excel

publisher excel endpoint

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
Status Codes
OPTIONS /publishers/{pipe_id}/excel/

publisher excel endpoint OPTIONS (for office)

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
GET /publishers/{pipe_id}/excel/{filename}

publisher excel endpoint - filename in url version

Parameters
  • pipe_id (string) -- The id of the pipe
  • filename (string) -- The filename to use as attachment filename
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
Status Codes
GET /publishers/{pipe_id}/xml

publisher xml endpoint

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
Status Codes
GET /publishers/{pipe_id}/xml/{filename}

publisher xml endpoint - filename in url version

Parameters
  • pipe_id (string) -- The id of the pipe
  • filename (string) -- The filename to use as attachment filename
Query Parameters
  • since (string) -- Specifies the minimum since-value.
  • limit (integer) -- Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..
Status Codes
OPTIONS /publishers/{pipe_id}/xml/

publisher xml endpoint OPTIONS (for office)

Parameters
  • pipe_id (string) -- The id of the pipe
Status Codes
POST /receivers/{pipe_id}/sdshare-push-receiver

Sesam api receiver endpoint - uses the SDShare Push protocol. Pushes n-triples to the named pipe. This is only supported for pipes that have an 'http_endpoint' source.

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • resource (string) -- Specifies the root resources
Status Codes
POST /receivers/{pipe_id}/entities

Sesam api receiver endpoint - uses the JSON Push protocol. Pushes JSON entities to the named pipe. This is only supported for pipes that have an 'http_endpoint' source.

Parameters
  • pipe_id (string) -- The id of the pipe
Query Parameters
  • sequence_id (string) -- A string token that is generated every time the data sync is started. Included in all requests.
  • is_full (boolean) -- A boolean. Has the value true if this is a full data sync, and false if not. Included in all requests. The default value is false.
  • request_id (string) -- A string token that is generated for every request. Included in all requests.
  • previous_request_id (string) -- A string token referencing the request_id of the previous request. Included in all but the first request.
  • is_first (boolean) -- A boolean. Included in the first request with the value true.
  • is_last (boolean) -- A boolean. Included in the last request with the value true.
Status Codes
GET /systems

Returns a list of all the systems

Status Codes
  • 200 OK -- An array of systems
POST /systems

Creates one or more systems

Query Parameters
  • force (boolean) -- When this is set to "true" it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.
Status Codes
  • 200 OK -- An array containing the new systems
GET /systems/{system_id}

Returns the specified system

Parameters
  • system_id (string) -- The id of the system
Status Codes
DELETE /systems/{system_id}

Deletes the specified system

Parameters
  • system_id (string) -- The id of the system
Status Codes
GET /systems/{system_id}/logs

Returns the logs from the microservice. By default it returns the last 1000 lines.

Parameters
  • system_id (string) -- The id of the system
Query Parameters
  • since (string) -- Specifies from which point in time to stream the logs. The value must be an ISO datetime value, e.g. '2016-11-08T08:28:45.880594510Z'. Note that all log lines after this point in the log will be returned.
Status Codes
  • 200 OK -- The microservice logs data
GET /systems/{system_id}/status

Returns the status from the system (if microservice, then a subset of docker inspect)

Parameters
  • system_id (string) -- The id of the system
Status Codes
  • 200 OK -- The microservice status data
POST /systems/{system_id}/reload

Queues a operation tp pull a new docker image and recreate the microservice (i.e. asynchronously)

Parameters
  • system_id (string) -- The id of the system
Status Codes
GET /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters
  • system_id (string) -- The id of the system
  • rest_of_path (string) -- The relative path to access on the microservice
Status Codes
  • 200 OK -- The proxied response from the microservice
POST /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters
  • system_id (string) -- The id of the system
  • rest_of_path (string) -- The relative path to access on the microservice
Status Codes
  • 200 OK -- The proxied response from the microservice
PUT /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters
  • system_id (string) -- The id of the system
  • rest_of_path (string) -- The relative path to access on the microservice
Status Codes
  • 200 OK -- The proxied response from the microservice
PATCH /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters
  • system_id (string) -- The id of the system
  • rest_of_path (string) -- The relative path to access on the microservice
Status Codes
  • 200 OK -- The proxied response from the microservice
DELETE /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters
  • system_id (string) -- The id of the system
  • rest_of_path (string) -- The relative path to access on the microservice
Status Codes
  • 200 OK -- The proxied response from the microservice
GET /systems/{system_id}/config

Returns the configuration of the specified system

Parameters
  • system_id (string) -- The id of the system
Status Codes
  • 200 OK -- The system configuration
PUT /systems/{system_id}/config

This service lets the user update a system's configuration by sending a PUT-request with the new configuration. The id of the system is specified by the '{system_id}' part of the url.

Parameters
  • system_id (string) -- The id of the system
Query Parameters
  • force (boolean) -- When this is set to "true" it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.
Status Codes
  • 200 OK -- The system configuration
GET /systems/{system_id}/secrets

Returns the names of the currently defined secrets for the specified system.

Parameters
  • system_id (string) -- The id of the system
Status Codes
PUT /systems/{system_id}/secrets

Overwrites the current secrets for the specified system.

Parameters
  • system_id (string) -- The id of the system
Status Codes
POST /systems/{system_id}/secrets

Adds a secret or list of secrets to the secrets manager for the specified system. If a secret already exists, it is overwritten.

Parameters
  • system_id (string) -- The id of the system
Status Codes
DELETE /systems/{system_id}/secrets/{secret_key}

Deleted the specified secret from the specified system

Parameters
  • system_id (string) -- The id of the system
  • secret_key (string) -- The name of the secret to delete
Status Codes

Portal API Reference

GET /api/profile

Returns information about the currently logged-in user.

Status Codes
PUT /api/profile

Updates information about the currently logged-in user. This endpoint accepts the same json structure as the GET /api/profile endpoint produces, but only a few of the fields in that structure will be used, since the user is only allowed to change a few of the fields. The "name" field can be changed, but the "email" field can not be changed, for instance. This endpoint also accept a "sparse" json-structure, that only contains the field(s) that the client wants to modify. The values represented by any "missing" fields will not be modified; if for instance the json only contains the "picture"-field, the "name"-field will not be modified.

Status Codes
GET /api/profile2

Returns information about the currently logged-in user. If the user is not logged in a 401 response is returned instead. TODO replace the "/api/profile" endpoint with this when we deploy the unified frontend.

Status Codes
  • 200 OK -- This returns the same response as the /api/profile endpoint
  • 401 Unauthorized -- The user is not logged in
DELETE /api/profile/{user_id}

Deletes the specified user.

Parameters
  • user_id (string) -- The id of the user to delete.
Status Codes
GET /api/jwt

Returns the JSON Web Token for the currently logged in user.

Status Codes
POST /api/jwt

Returns the JSON Web Token for the user described in the post parameters (email+password).

Status Codes
GET /api/subscriptions/{subscription_id}/jwt

Returns the JSON Web Token for the specified subscription for the currently logged in user.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/jwt/publickey

Returns the RSA public key that can be used to verify the JWT signature

Status Codes
GET /api/subscriptions

Returns the subscriptions that this user is connected to.

Status Codes
POST /api/subscriptions

Creates a new subscription

Status Codes
GET /api/subscriptions/{subscription_id}

Returns information about the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
DELETE /api/subscriptions/{subscription_id}

Deletes the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
PUT /api/subscriptions/{subscription_id}

Update the subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/subscriptions/{subscription_id}/available-roles

Returns a list of the roles that are available for the specified subscription. This includes the build-in roles and any custom-roles that has been created in the subscription.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/subscriptions/{subscription_id}/available-roles

Adds a new custom-role.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/subscriptions/{subscription_id}/licenses

Renews the subscription's license. This extends the current license's expirationdate, but keeps all other license-values the same. Returns the updated Subscription.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/subscriptions/{subscription_id}/api_json_web_tokens

Returns a list of the api JWT tokens for this subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/subscriptions/{subscription_id}/api_json_web_tokens

Creates a new API JWT for the specified subscription. These are json web tokens that are intended for use by things like scripts and cron-jobs, where you need a long-lasting JWT with a specific set of roles.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
  • 200 OK -- The new SubscriptionJWT
DELETE /api/subscriptions/{subscription_id}/api_json_web_tokens/{api_json_web_token_id}

Deletes the specified api JWT token

Parameters
  • subscription_id (string) -- The subscription id
  • api_json_web_token_id (string) -- The api jwt id
Status Codes
GET /api/subscriptions/{subscription_id}/available-roles/{role_id}

Returns information about the specified role in the specified subscription.

Parameters
  • subscription_id (string) -- The subscription id
  • role_id (string) -- The role id
Status Codes
DELETE /api/subscriptions/{subscription_id}/available-roles/{role_id}

Deletes the specified role in the specified subscription.

Parameters
  • subscription_id (string) -- The subscription id
  • role_id (string) -- The role id
Status Codes
PUT /api/subscriptions/{subscription_id}/available-roles/{role_id}

Updates the specified role in the specified subscription.

Parameters
  • subscription_id (string) -- The subscription id
  • role_id (string) -- The role id
Status Codes
GET /api/subscriptions/{subscription_id}/members

returns a list of the members in the subscription

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • limit (integer) -- Specifies the maximum number of members to return. If this is not specified, all available members are returned.
  • start (integer) -- The index of the first member to return. This defaults to 0 (zero), which means to start at the beginning of the list of members. The 'start' parameter can be used in conjunction with the 'limit' parameter to implement pagination.
Status Codes
POST /api/subscriptions/{subscription_id}/members

Invites a user to the subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/subscriptions/{subscription_id}/members/{user_id}

returns information about the roles the specified user has in the subscription

Parameters
  • subscription_id (string) -- The subscription id
  • user_id (string) -- The user id
Status Codes
PUT /api/subscriptions/{subscription_id}/members/{user_id}

updates the roles the specified user has in the subscription

Parameters
  • subscription_id (string) -- The subscription id
  • user_id (string) -- The user id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/available-notification-ruletypes

Returns a list of the available notification rule types on the specified pipe. The idea is that the client can use this list to dynamically generate a gui that lets the user add and edit notification rules.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
PUT /api/admin/config/validation_hack_for_NewPipeNotificationRuleInfo

This is a dummy endpoint that is used to register the NewPipeNotificationRuleInfo definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
POST /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules

Add a new notification rule entry on the specified pipe

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules

Returns a list of the notification rules on the specified pipe

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
PUT /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Updates the specified notification rule entry.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Gets the specified notification rule entry.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Status Codes
DELETE /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Deletes the specified notification rule entry.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}/notifications

Returns the notifications that has been triggered by the specified notification rule.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Query Parameters
  • limit (integer) -- Specifies the maximum number of notifications to return. If this is not specified, a reasonable default limit will still be used.
  • since (string) -- This can be set to a ISO 8601 datetime string to only return notifications that are more recent than the specified datetime.
  • include_dismissed (boolean) -- Specified if dismissed notifications should be included in the results.
Status Codes
GET /api/notifications

Returns the notifications that should be displayed in the "Announcement"-list for this user.

Query Parameters
  • limit (integer) -- Specifies the maximum number of notifications to return. If this is not specified, a reasonable default limit will still be used.
  • since (string) -- This can be set to a ISO 8601 datetime string to only return notifications that are more recent than the specified datetime.
  • include_dismissed (boolean) -- Specified if dismissed notifications should be included in the results.
Status Codes
GET /api/monitoring/standard/{subscription_id}/pipes/{pipe_id}

Returns standard monitoring information about the specified pipe

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
GET /api/monitoring/standard/{subscription_id}

Returns standard monitoring information about the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/monitoring/invoicing/{subscription_id}

Returns invoicing information for the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/login

This is called when the user wants to authenticate with a email-address and a password. If the login is successful, a new http session is created, and the sessionid is returned in a cookie.

Status Codes
GET /api/logout

Logs out the currently logged-in user, and clears the http session data.

Status Codes
POST /api/signup

Signs up a new user

Status Codes
GET /api/available-subscription-settings

service for returning the various choices that exists for the various subscription settings

Status Codes
POST /api/estimate-subscription-price

service for calculating subscription price, based on a description of the select subscription options

Status Codes
POST /api/subscriptions/{subscription_id}/estimate-subscription-price

service for calculating a new subscription price, based on a description of the select subscription options

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/is-available-subscription-name

This service checks that the specified subscription name is unique for specified "owner" and that is a valid name.

Status Codes
POST /api/request_trial

This is called when a user wants to request a trial subscription.

Status Codes
POST /api/cancel_request_trial

This is called when a user wants to cancel a previously made 'create trial' request.

Status Codes
POST /api/dismiss_denied_request_trial

This is called when a user wants to dismiss a denied 'create trial' request (so that the request doens't show up in the user's gui any longer).

Status Codes
PUT /api/password

Changes the password of the user. This is called when a user is logged in, but wants to change their password.

Status Codes
POST /api/forgot-password

Sends a mail to the specified emailaddress with a one-time link that lets the user change the password. The link leads to the normal gui with a url parameter that contains the "change-password" one-time token.

Status Codes
POST /api/reset-password

changes the user's password. This is part of the "forgotten password" flow.

Status Codes
POST /api/verify-emailaddress

Verifies the user's email address. This is part of the "verify emailaddress" flow.

Status Codes
  • 200 OK -- OK, address has been verified
  • 400 Bad Request -- Token might be invalid, already used or expired
POST /api/request-email-verification

Asks the portal to send a new 'Verify emailaddress' email.

Status Codes
  • 200 OK -- OK, a new email has been sent
  • 409 Conflict -- The current user already has a pending 'verify emailaddress email', so no new email can be sent at this time.
GET /api/status

Returns misc information about the portal

Status Codes
GET /api/payment/stripe_publishable_api_key

Returns the Stripe publishable api key.

Status Codes
POST /api/payment/stripe_coupon

Returns a coupon if it exists

Status Codes
POST /api/payment/subscription

Creates a new customer and subscription in Stripe and creates a PaymentMethod in the Sesam portal. Also creates a new gdpr subscription in the Sesam Portal (using the new paymentmethod).

Status Codes
GET /api/paymentmethods

Returns the paymentmethods that this user owns.

Status Codes
POST /api/paymentmethods

Creates a new paymentmethod

Status Codes
GET /api/paymentmethods/{paymentmethod_id}

Returns information about the specified paymentmethod

Parameters
  • paymentmethod_id (string) -- The paymentmethod id
Status Codes
DELETE /api/paymentmethods/{paymentmethod_id}

Deletes the specified paymentmethod

Parameters
  • paymentmethod_id (string) -- The paymentmethod id
Status Codes
PUT /api/paymentmethods/{paymentmethod_id}

Update the paymentmethod

Parameters
  • paymentmethod_id (string) -- The paymentmethod id
Status Codes
GET /api/admin

Returns a simple htmlpage that lets portal admin perform various operations. This should probably be replaces with a proper fancy page in the normal javascript GUI, but we want the functionality quickly, and only sesam employees will ever see it.

Status Codes
POST /api/admin

Handles POSTs for the various forms on the main admin-page.

Status Codes

Returns a simple htmlpage that lets admins search for subscriptions and perform various operations on them.

Status Codes
POST /api/admin/search

Handles POSTs for the various forms on the search-page.

Status Codes
GET /api/admin/portal_administrators

Returns a simple htmlpage that display the current portal admins.

Status Codes
POST /api/admin/portal_administrators

Handles POSTs for the various forms on the portal_admins-page.

Status Codes
GET /api/admin/delete_user

Returns a simple htmlpage that lets the admin delete users

Status Codes
POST /api/admin/delete_user

Handles POSTs for the various forms on the delete_user-page.

Status Codes
POST /api/admin/throw_exception

This is a test-endpoint for throwing various exceptions. This is used in ci-tests to verify that exceptions of various types are logged correctly.

Status Codes
GET /api/admin/config_gui

Returns a gui for examining and modifying the portal configuration.

Status Codes
GET /api/admin/pre_created_subscriptions

Returns a gui for examining and modifying the "pre-created subscriptions" settings.

Status Codes
GET /api/admin/config

Returns the current runtime configuration of the Portal. This is config that is intended to be modified at runtime (as opposed to stuff like database usernames and passwords, which is specified in the sesamportal.yaml file). See the definition of the ConfigEntity model and it's child models.

Status Codes
POST /api/admin/config

Adds one or more new runtime configuration entries to the Portal.

Status Codes
PUT /api/admin/config/validation_hack_for_SubscriptionJWT

This is a dummy endpoint that is used to register the SubscriptionJWT definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_AutoJoinSubscriptionGroup

This is a dummy endpoint that is used to register the AutoJoinSubscriptionGroup definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_PreCreatedSubscription

This is a dummy endpoint that is used to register the PreCreatedSubscription definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_RateLimits

This is a dummy endpoint that is used to register the RateLimits definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/{config_entity_id}

Updates the specified configuration entry.

Parameters
  • config_entity_id (string) -- The config entity id
Status Codes
GET /api/admin/config/{config_entity_id}

Returns the specified configuration entry.

Parameters
  • config_entity_id (string) -- The config entity id
Status Codes
DELETE /api/admin/config/{config_entity_id}

Deletes the specified configuration entry.

Parameters
  • config_entity_id (string) -- The config entity id
Status Codes
GET /api/subscriptions/{subscription_id}/revoked_json_web_tokens

Returns a list of revoked json web tokens. Note that this includes both the transient JWTs that are issued by the unified GUI to talk to the node, and the special API JWTs that are typically very long-lived. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a user's permissions have been modified, and when an api JWT has been revoked.

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • since (string) -- Specifies that the endpoint should only return entities newer than the specified 'since' value. The since-value should be set to the value of the "_updated"-attribute in the last seen entity. See https://docs.sesam.io/configuration.html#continuation-support for details on how this works.
Status Codes
GET /api/subscriptions/{subscription_id}/updated_licences

Returns a list of updated licenses. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a subscription's lisence has been upgraded.

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • since (string) -- Specifies that the endpoint should only return entities newer than the specified 'since' value. The since-value should be set to the value of the "_updated"-attribute in the last seen entity. See https://docs.sesam.io/configuration.html#continuation-support for details on how this works.
Status Codes
GET /api/provisioning/domain

Returns information about availability of a domain name.

Query Parameters
  • fqdn (string) --
  • subscription_id (string) --
Status Codes
POST /api/feedback

Submits feedback from the feedback form to Slack

Status Codes

Swagger Files

To access the Swagger endpoint for your instance go to https://<your-instance>/api/reference.

For the Portal API go to the Autogenerated Swagger Endpoint for the Portal.