Get Started¶

Once the web server is running, the API can be called. If you want to experiment with the API using Swagger, you can visit "<path-to-comos-web>:<configured-port>/swagger/index#/". The recommended procedure for using the API is as follows.

1. The client calls the discovery endpoint. The discovery endpoint gives information on the available features and should be used to discover the actual URLs of the other features. Please refer to the section on Discovery for further details.

2. The client logs in. On a successful login, a session ID is returned. This session ID has to be provided for almost all the remaining calls to the COMOS Web REST API. The client can provide the session ID to the COMOS Web REST API in one of the following ways:

   • Via the HTTP header COMOS-API-Session

   • Via an HTTP cookie-header with a cookie named Comos.Api.Session

   Note that this session ID is not an authentication token. Nevertheless, it can only be used by the same account that was used to log in. Please refer to the section on Authentication and Authorization for further details.

   Example of a response from the "public/api/sessions/v1/sessions/actions/login" endpoint

   {
   "SessionId": "3797870ad22g44e6ra83fd72e84d2a09",
   "UserName": "your user name",
   "HeartbeatInterval": 60
   }
   

3. The client calls the features of the COMOS Web REST API. The client must use the relative paths provided by the discovery to assemble the target URL, and it usually has to provide the session ID in one of the above-mentioned ways.

4. The client logs out.

Discovery¶

The available features of the COMOS Web REST API can be called and addressed via its "discovery" feature. Each feature of the COMOS Web REST API has its own version. This enables a client to decide about the compatibility for each feature individually and hence give detailed feedback to the user. A breaking change in a feature, leading to incompatibility with previous versions, does not influence the whole API but just this specific feature.

The available features can be requested via an "HTTP GET" request at the following path: "public/api/discovery/v1/services"

[
  {
    "Name": "projects",
    "Versions": [{"VersionNumber": "1.0.0", "Path": "api/projects/v1"}]
  },
  {
    "Name": "discovery",
    "Versions": [{"VersionNumber": "1.0.0", "Path": "api/discovery/v1"}]
  },
  {
    "Name": "users",
    "Versions": [{"VersionNumber": "1.0.0", "Path": "api/users/v1"}]
  },
  {
    "Name": "sessions",
    "Versions": [{"VersionNumber": "1.0.0", "Path": "api/sessions/v1"}]
  }
]

The Name property contains the name of the feature. This name will not change during the evolution of the API. The Versions property contains a list of all currently available versions for this feature. A feature might be available in multiple versions. Each version has a VersionNumber in the Semantic versioning format as well as the path to the feature. This is the relative path, which has to be added to the base address of the COMOS Web REST API, including the "public".

A client SHOULD use discovery to get the actual URL of a specific service. The only feature whose relative URL is fixed is the discovery feature with the MAJOR version 1. Hence, a client SHOULD call discovery before sending another API request.

A client SHOULD NOT use a fixed reference to a specific URL of the API except the URL used for discovery.

Authentication and Authorization¶

• The Rest API supports "Windows authentication" and "Two-factor authentication" via OpenId Connect.
• Swagger only supports Windows authentication.
• All requests to the Rest API must include valid headers, e.g.:
  • Comos-Api-Session: The session id received when using the login endpoint
  • A cookie header containing a cookie called Comos.Api.Session