Skip to main content
Version: ADONIS 16/ADOIT 17/ADOGRC 13

API Guide

This document explains how to use this REST API to send requests to the ADOXX-based product using the desired authentication mechanism.

Technical Overview​

ADOXX RESTful services are based on "JAX-RS", a programming language API which facilitates creating a RESTful interface. ADOXX-based products use JAX-RS' reference implementation "Jersey".

Jersey is very well documented, and contains elaborate Jersey API documentation

The addresses for RESTful services exposed by ADOXX-based products use the following pattern:
https://<SERVER_NAME>:<PORT>/<PRODUCT><VERSION>/rest/[service path]

Where everything before [service path] is the fixed path and the part(s) afterwards are defined by the service.

Example

You are configuring ADOXX. You are running the ADOXX web application locally. The ADOXX web application exposes a REST service called "helloworld". The URL should look like this:
https://localhost:8000/ADOXX/rest/helloworld

For testing purposes, the following URLs are always available: https://<SERVER_NAME>:<PORT>/<PRODUCT><VERSION>/rest/connection https://<SERVER_NAME>:<PORT>/<PRODUCT><VERSION>/rest/connection/auth (requires authentication - see Authentication)

OpenAPI Specification​

The REST API Specification is documented with the standard Open API Specification (OAS), and can be downloaded directly from Github

Based on the OAS definition the developer portal provides a frontend for each API endpoint that shows the documentation and how to use the API. We provide a comprehensive overview of REST API endpoints which shows the documentation In addition all endpoints can be retrieved by accessing the /openapi.json endpoint.

Getting started with REST API​

BOC products offer a generic and extensible REST API that allows autehnticated acces to exposed functionality. The REST API can be used to e.g. send GET request to query for data.

note

Instructions on how to activate and configure access to the REST API are covered in the Administration Manual.

OR get started right away by using any of BOC's cloud solutions. REST is coming to the Community Edition products soon!

This example shows how to retrieve all available repositories by using the rest/4.0/repos endpoint.

Use the Swagger documentation to find endpoints that you can use to support your use case. In the following screenshot, the endpoint to list the available repositories is chosen. Repository Read endpoint

There are many methods to try out endpoints. Untill try it out functionality in the web browser is enabled we will demonstrate how to call the endpoints through Postman. To perform a REST call, make sure to fill out the properties as described below:

  1. HTTP Method: Select GET, POST, PUT, PATCh or DELETE in the dropdown menu next to the Base URL

  2. Base URL: Enter the base URL for the web ervice endpoint.

  3. Resource Path: Enter the path to the complete web service endpoint. In the example below we aim to retrieve a list of all repositories. The endpoint for that is rest/4.0/repos

  4. Query Parameters: Undereath the Base URL input a tab presents itself called Params. Optionally for certain endpoints one could append parameters to the call.

  5. Authorization: Underneath the Base URL input, and next to the Params tab it is required to select Basic Auth. The authorization header will be automatically generated when you send the request. Fill in the Username field and the Password field according to your credentials used to log in to the application.

  6. Response: After clicking send, an response should be returned. In the example below we obtain a json containing a list of repositories.

Postman Response

Coming Soon "Try it out"

We will soon enable a "try it out" functionality with basic authentication to allow you to test the APIs directly.

Authentication​

ADOXX RESTful services support three authentication mechanisms:

  • Token Based Authentication Each request is accompanied by Hashed security token to ensure validity of the request. Requests are executed in the context of a technical user.
  • Basic authentication: Each request contains the header "Authorization" where the value is the username and password separated by a single colon (:) character, within a base64 encoded string. Requests may be executed in the context of any standard product user.
  • OAuth 2.0: Each request is accompanied by an access token to ensure validity of the request. Two OAuth 2.0 flows are supported:
  • JWT: JWT authentication enables the use of an external identity provider (IdP) for user authentication. A JSON Web Token (JWT) acquired from the IdP is used for authentication as well as for the optional transport of user properties via claims encoded in the token. Requests may be executed in the context of any standard product user.