wapi.md

Web API

This section explains how to use Onix Web API.

Quick Index (back)

Good to know

Area	Description
Using Swagger	How to access online Web API documents?
Access Control	How to authenticate and authorise users?
Getting WAPI information	How to get the Web API version online?
HTTP return codes	Which codes Web API return?
HTTP Result	What data is returned by the service when resources are created, updated or deleted?
Concurrency Management	How to use the Web API in concurrent user scenarios?
Automation Clients	How do I apply this documentation to Ansible and Terraform clients?
Idempotence	What happens if I make repeated requests to the same endpoint with the same payload?
Change History	Is every change made recorded?
Versioning	Can I version CMDB data?

Reference data: working with models

Area	Description
Models	How to create a new or update or delete an existing model definition?
Item types	How to create a new or update or delete an existing item definition?
Link types	How to create a new or update or delete an existing link definition?
Link rules	How to create a new or update or delete an existing link rule?

Instance data: feeding and querying the database

Area	Description
Items	How to create a new or update or delete an existing item type?
Links	How to create a new or update or delete an existing link type?

Using Swagger (up)

Onix uses Swagger to document its web API.

Swagger UI

When Onix is up and running, the Swagger User Interface can be reached at the following URI:

http://localhost:8080/swagger-ui.html

Authenticating Users

If the Web API is set to use Basic authentication, the browser will display a user credentials challenge window and automatcally create a base 64 encoded basic authentication header.

However, if the Web API is set to use OpenId for authentication then the Swagger UI will need to send a Bearer token to the server. To this extent, an "Authorize" button will show at the top right corner of the Swagger UI if auth_mode is set to oidc.

Use this button to set the Bearer token required for authentication and authorisation purposes. If a token is not set then access to the Web API resources will be forbidden.

Obtaining a Bearer token

In order to get a bearer token use the cURL command below, replacing the following variables with the correct values:

• token_endpoint_url
• base64_encoded_client_id_and_secret (use this online tool to create the token using the OAuth server application client id and secret)
• user_name_here
• user_password_here

curl --request POST \
 --url 'token_endpoint_url' \
 --header 'accept: application/json' \
 --header 'Authorization: Basic base64_encoded_client_id_and_secret' \
 --header 'cache-control: no-cache' \
 --header 'content-type: application/x-www-form-urlencoded' \
 --data 'grant_type=password&username=user_name_here&password=user_password_here&scope=openid%20onix'

The result should look like the following:

{
 "access_token":"eyJraWQiO...sAg",
 "token_type":"Bearer",
 "expires_in":3600,
 "scope":"onix openid",
 "id_token":"eyJraW...1Q"
}

• Extract the access_token variable from the response above.
• Create a string with the format "Bearer access_token_value"
• Paste it in the value textbox of the "Available authorizations" popup modal window that shows after clicking on the "Authorize" button on the Swagger UI:

Then click on "Authorize". Now every Swagger UI request will send the Bearer token as an Authorization header.

NOTE: the bearer token is set to expire after a period defined by the authorization server access policy. In the example above it is set to expire after 3600 seconds or 1 hour. After this time, the bearer token will have to be reset to prevent unauthorised access errors.

JSON WAPI Docs

Similarly, a JSON representation of the Web API documentation can be retrieved from the following URI:

http://localhost:8080/v2/api-docs

Access Control (up)

If the Onix Service is configured with 'WAPI_AUTH_MODE=basic', then a basic authentication token must be passed with every request via an authorisation header. The following example shows how to obtain a token and pass it to the service:

# executes the request passing the credentials using the -u otion
curl -u username:password 'http://localhost:8080/itemtype/'

To generate a token that can be passed via the http header a generator like this can be used. Then, the token can be passed to the API call as follows:

# executes the request passing the credentials using the -u otion
curl -H 'Authorization: TOKEN_HERE' 'http://localhost:8080/itemtype/'

Authentication Modes

Mode	Description	Setting
None	No authentication is required. This is mainly used for development activities where authentication is not required.	AUTH_MODE=none
Basic Auth	Basic authentication distinct reader, writer and admin credentials.	AUTH_MODE=basic
OIDC[*]	OpenID Connect supporting identity and access tokens.	AUTH_MODE=oidc

[*] This is currently work in progress and subject of the next release.

Getting WAPI Information (up)

The root of the service displays service information.

Item	Value
Method	GET
Path	/
Response Content Type	application/json

Usage example

$ curl -u admin:0n1x 'http://localhost:8080'

Return values

Attribute	Description
description	name of the service
version	version of the release

HTTP Return Codes (up)

For any resource acting on CMDB entities, the following codes are returned by the HTTP requests:

Code	Method	Description
200	GET, PUT (U, L, N), DELETE	Successful HTTP request
201	PUT (I)	Successful HTTP request
401	PUT, GET, DELETE	Unauthorised HTTP request
404	PUT, GET, DELETE	Resource not found
500	PUT, GET, DELETE	Internal server error

For PUT, DELETE and GET HTTP methods, the following operations are available:

Code	Operation	Description
I	Insert	entity inserted
U	Update	entity updated
D	Delete	entity deleted
L	Lock	no action taken, version on the client does not match the version on the server
N	None	no action taken, client and server data match

HTTP Result (up)

In the case of PUT and DELETE HTTP methods, a Result object is returned containing information about the request process as follows:

Attribute	Description
ref	a reference containing the entity type and natural key
operation	a character indicating the type of operation executed; namely I, U, D, L or N as described in the table above.
changed	true if the entity was created, updated or deleted
error	true if there was a problem processing the request
message	an error message in case error is true

Concurrency Management (up)

Every time a resource is updated, an incremental version number is automatically assigned to the resource.

All resource requests can accept a version number when an HTTP PUT method is requested. The version number enables optimistic concurrency control.

If no version number is specified in the PUT request, concurrency is disabled. However, if a value is specified, the following outcomes are possible:

1. Insert or Update: an insert/update occurs if the client version number matches the server version number.
2. Optimistic Lock: no action is taken if the client version number is behind the server version number. The response contains an L operation which means that some other client has updated the state of the resource since the last time a copy was retrieved. This feature is helpful for user interfaces updating resources where more than one client could be acting on the same resource at the same time. The client has the option to: a) override the server by sending the request again without a version number; or b) refreshing the client with the new data from the server.

Automation Clients (up)

Onix integrates with Ansible (via Ansible Modules) and Terraform (via a Terraform Provider).

Each of the Web API resources maps directly to an Ansible Module or a Terraform Resource/Data Source. Therefore, in order to avoid maintaining multiple document sets, this document should be used to determine which attributes are available for each resource within both, Ansible and Terraform (TF).

The following table provides a convention for translating Web API resources into Ansible module names, Terraform resource names and Terraform data source names:

Web API Resource	Ansible Module	TF Resource	TF Data Source
model	ox_model	ox_model	ox_model_data
itemtype	ox_item_type	ox_item_type	ox_item_type_data
linktype	ox_link_type	ox_link_type	ox_link_type_data
linkrule	ox_link_rule	ox_link_rule	ox_link_rule_data
item	ox_item	ox_item	ox_item_data
link	ox_link	ox_link	ox_link_data

Idempotence (up)

All HTTP resources in the Web API are idempotent.

Resources are uniquely identified by a natural key. The natural key is a string with a value that should be decided using a naming convention that is chosen by the implementer.

Using a natural key, for example, in HTTP PUT methods, allow the client to avoid having to think if the HTTP resource has to be created or updated. The request ensures that the resource information is in the CMDB regardless of how many times the method is invoqued.

When a PUT method is executed for the first time, the resource is created. Any subsequent calls to the same method will result in updates if the payload has changed, or no action will be taken if the payload is the same.

Change History (up)

Every time a CMDB entity is created, updated or deleted, their data get written into change tables recording the type of operation (i.e. Insert, Update or Delete), the date of the change and the user that made the change.

Preserving the whole history of changes allows to retrieve any configuration at any point in time.

Versioning (up)

Every entity in the CMDB has a version number starting with 1, which increments automatically when changes are made.

In order to retrieve a configuration, that is a set of items and links at a specific point in time, a tag needs to be created. The tag carries the information of which items and links where related to a specified item at a specified point in time.

Creating a tag in the CMDB is equivalent to creating a tag in Git.

Models (up)

In order to create items, it is first necessary to create a model, that is a set of item and link definitions (i.e. item types and link types).

Item and Link Types have to belong to one and only one model. A model can be created as described below.

Create or Update

To create or update a model use the PUT HTTP method.

Request attributes

Item	Value
Method	PUT
Path	/model/{model_key}
Response Content Type	application/json
Authentication Header	basic authentication token

Request payload

Attribute	Description	Example	Mandatory
name	the human readable name of the model	"AWS EC2 Model"	yes (unique)
description	the model description	"Definitions for AWS Elastic Compute Cloud items and their relationships"	no
version	the version of the model for concurrency management purposes.	34	no

Usage

The PUT request requires a payload in JSON format as the one shown below. Note that the natural key for the configuration item type is not part of the payload but specified in the URI.

$ curl \
    -X PUT \
    -H 'ContentType: application/json' \
    -H '${AUTH_HEADER}' \
    -d '@model_payload.json' \
    'http://localhost:8080/model/awsec2' 

model_payload.json:

{
  "name": "AWS EC2 Model",
  "description": "Definitions for AWS Elastic Compute Cloud items and their relationships."
}

result:

{
  "ref": "model:awsec2",
  "changed": "true",
  "error": "false",
  "message": "", 
  "operation": "I", 
}

Delete

In order to delete a model the following command can be executed:

$ curl \
    -X DELETE \
    -H '${AUTH_HEADER}' \
    'http://localhost:8080/model/awsec2' 

NOTE: deleting a Model, forces the deletion of the Link Types and Item Types related to that Model. Item and Links have to be deleted before a model can be deleted.

Query

The following model queries are available:

Query	Description
GET /model/{model_key}	Retrieve the model for the specified natural key.
GET /model/{model_key}/data	Retrieve a list of Item Types and Link Types that comprise the specified model.
GET /models	Retrieve a list of all models in the system.

---

Item Types (up)

Item Types provide the definition of items. Items can record data in two main ways:

• Using a JSON object (meta field)
• Using Key/Value pairs (attribute field)

Item types can be used to apply specific validation to the data recorded by a configuration item by defining a JSON schema or key/value required/mandatory constraints.

Create or Update

To create or update an Item Type use the PUT HTTP method.

Request attributes

Item	Value
Method	PUT
Path	/itemtype/{item_type_key}
Response Content Type	application/json
Authentication Header	basic authentication token

Request payload

Attribute	Description	Example	Mandatory
name	the human readable name of the item type	"AWS Instance"	yes (unique)
description	the item type description	"A Virtual Machine running on Aws EC2"	no
version	the version of the model for concurrency management purposes.	21	no

Usage

The PUT request requires a payload in JSON format as the one shown below. Note that the natural key for the configuration item type is not part of the payload but specified in the URI.

$ curl \
    -X PUT \
    -H 'ContentType: application/json' \
    -H '${AUTH_HEADER}' \
    -d '@item_type_payload.json' \
    'http://localhost:8080/itemtype/AWS_INSTANCE' 

item_type_payload.json:

{
  "name": "AWS Instance",
  "description": "An Virtual Machine in AWS EC2.",
  "modelKey": "meta_model_1"
}

result:

{
  "ref": "itemType:AWS_INSTANCE",
  "changed": "true",
  "error": "false",
  "message": "",
  "operation": "I"
}

Delete

In order to delete an item type the following command can be executed:

$ curl \
    -X DELETE \
    -H '${AUTH_HEADER}' \
    'http://localhost:8080/itemtype/AWS_INSTANCE' 

Query

The following model queries are available:

Query	Description
GET /itemtype/{item_type_key}	Retrieve the item type for the specified natural key.
GET /itemtype	Retrieve a list of all item types in the system.

---

Using Swagger for Documentation

As all resources in the Web API are documented using Swagger, it makes sense to look at the Onix WAPI Swagger UI for a full reference.

The Swagger UI which can be found under the http(s)://host:port/swagger-ui.html URL.