API service

OnSphere api services allow to configure api access. The api is usable from a dashboard (menu, form, …) or script. The communication with the api is done by the backend which allow to limit the access depending on the user and permit to access a private api from anywhere.

Capabilities

Feature	Supported	Note
Client HTTP		The system consume HTTP endpoints
Client HTTPS		The system consume HTTPS endpoints
Disable HTTPS certificate validation		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Authentication “no-auth”
Authentication basic		Authentication using user/password
Authentication bearer		Authentication using a bearer token
Authentication OIDC		Authentication using a token retrieved from a OpenIdConnect token endpoint
Authentication with custom header		Authentication using a custom header like API key
Authentication with other method		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Session		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Connection state monitoring		The system is not link to a value, to survey the connection a script can be used
Query parameters		Added at the end of the request
Path parameters		Placeholder on the endpoint
Custom HTTP header		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Body		Only json
Validation of the json body		The body of the request can be validate by a schema.ospp
Extract data from the response body		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Content-type in json format		The content type must be json formatted
Other content-type		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Validation of the response		The response can be validate by a schema.ospp
Filter of the response		The response can be filter to only allow field define on the schema.ospp

Examples

• API service for http request

Concept

Service

The api-service.ospp define the host and credential to access the API.

The host must include the protocol (http or https).

The available credentials options are :

• No auth

• Basic auth

• Bearer

  Warning

  The token might expire and this will fail the subsequent request.

• OIDC

  The service will query the OIDC token endpoint to retrieve a temporary access token for authentication purposes.

  Warning

  The response of the token endpoint must be one of the following:

  • Success:

    Field	Description
    access_token	The generate token
    token_type	The type use for the authorization header
    expires_in	(Optional) The validity of the token in seconds

  • Error:

    Field	Description
    error	The name of the error
    error_description	(Optional) A description of the error
    error_uri	(Optional) A link to a external documentation

  • Custom header

    Some service rely on custom header to provide the API key. This credential type allow to inject them into the request.

Endpoint

The api-endpoint.ospp define the accessible endpoints and theirs parameters.

Rights

This offer a fine grain management of the rights. The following rights are required to interact with the API.

• READ for GET request

• WRITE for PUT, PATCH, POST and DELETE

Warning

The right is only check for the api-endpoint.ospp during the execution of a request. The right defined on api-service.ospp are ignored.

Parameters

The parameters configuration define which parameters are accessible when doing a request. It can be used to limit the available parameters for the final user.

Warning

The parameter reservedServiceId is reserved and must not be used as a parameter name.

Their can be of either types:

• QUERY: The parameter will be added after a ? with the format name=value at the end of the query.

  For example, https://example.org/user will become https://example.org/user?id=5.

  All query parameter will be url encoded before the request is done.

• PATH: The name will be used as a placeholder {name} on the endpoint and replace it with the value.

  For example, https://example.org/user/{id} will become https://example.org/user/5.

  Warning

  The value is sanitized before doing the request with the following action:

  • The character / is removed.

  • The data is url encoded.

  This is done to avoid injection on the request url.

  For example with the request https://example.org/{parameter}, if the user feed the parameter id/te st?toto=tutu, the final request will be https://example.org/idte+st%3Ftoto=tutu.

• BODY: Will define the body of the request.

  The body can be validate by a schema if the content-type is JSON.

  Warning

  The Body parameter must be unique per endpoint.

They can define a default value to avoid the need to set it every time.

Note

A parameter with a default value will always be used.

If a parameter is defined as mandatory, it must be defined either by user-defined or have a default value. User input always takes precedence.

Warning

The PATH parameters are always mandatory.

Response validation

Linking a schema to a endpoint allow to :

• check the response

  This ensure that format and content of the response is valid for the subsequent process.

• filter the response

  This allow to keep only a limited set of field to reduce the size of the data or hide information.

The check or filter can be combine or use separately but they both use the same schema.ospp.

For example, if an api return :

{
  "args": {
    "pageindex": "0",
    "pagesize": "10"
  },
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "gzip, deflate, br",
    "Cache-Control": "no-cache",
    "Content-Length": "139",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "Postman-Token": "3eedaf36-2e39-47e9-bdc7-43131ed0a7a8",
    "User-Agent": "PostmanRuntime/7.37.3",
    "X-Amzn-Trace-Id": "Root=1-67c1ab96-5b2f154c21ca739c6c1d8106"
  },
  "origin": "46.14.125.129",
  "url": "https://httpbin.org/get?pageindex=0&pagesize=10"
}

The schema :

{
  "type": "object",
  "properties": {
    "args": {
      "type": "object",
      "properties": {
        "pagesize": {
          "type": "string"
        },
        "pageindex": {
          "type": "string"
        }
      },
      "required": [
        "pagesize",
        "pageindex"
      ]
    },
    "url": {
      "type": "string"
    }
  }
}

validate that args.pagesize and args.pageindex are present and of type string.

If use as a filter, the response will be striped to obtain:

{
  "args": {
    "pageindex": "0",
    "pagesize": "10"
  },
  "url": "https://httpbin.org/get?pageindex=0&pagesize=10"
}

Usage

When calling an endpoint, the ItemId of the endpoint and a map containing the parameter are needed.

The parameters are represented as a map with the name and the value of the parameter as string.

For example:

{
  "id": "5",
  "body" : "My message",
  "other": "test"
}