REST API

Every application automatically gets its own REST API. You can use this for integrating your Appivo-application with other systems. This page will provide you with the necessary details to do so, including a few examples. You can of course use Postman or CURL or your favourite programming language / HTTP-client to access the API.

Authentication

First of all, to access the API you must authenticate and get an access-token. Appivo uses bearer-tokens in the JWT-format . You can get an access-token in two ways – either by calling the login-API or by issuing an API-key (which is just a different kind of token). To issue an API-key hover over your user avatar in the top right corner and click on your name, it will take you to this page https://apps.appivo.com/#/profile, click on the “API-keys” tab in the left panel and then create a new API-key.

Once you have an access-token you simple pass it along in the ‘Authorization’-header with your access-token prefixed by the keyword ‘Bearer’ and a space in between:

Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

Log in API

To log in send a request on the following format:

POST https://apps.appivo.com/api/login

Content-type: application/json

{
   "user": "johan@appivo.com",
   "password": "HelloWorld2020"
}

If the user name and password are correct you will get a 200-response, if not a 403. If the response is successful the ‘Authorization’-header will include your access-token.

Application API

Each application has it’s on API-space residing under a base-URL on the format:

https://apps.appivo.com/api/app/<appname>

Where appname is the name of your application. In the examples below we will be using ‘MyApp’ as the application-name.

Model API

The model API is read only and provides a way for you to access meta data about your application models. The base URL for your applications model API is on the format:

https://apps.appivo.com/api/app/<appname>/model/

List all models

To get meta data for all the models of your application, issue a GET-request to the model base URL. It will return a JSON-array of models.

GET https://apps.appivo.com/api/app/MyApp/model

Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

Get a specific model

If you want to get just the meta data for a single model you can access it via its unique URL by appending the model-name. Such a request will return a single JSON-document describing the requested model.

GET https://apps.appivo.com/api/app/MyApp/model/MyModel

Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

Record API

The record API resides in a subspace of the model API with a base URL on the form::

https://apps.appivo.com/api/app/<appname>/model/<modelname>/record

An individual record is accessed at its own unique URL which includes its ID on this form :

https://apps.appivo.com/api/app/<appname>/model/<modelname>/record/<id>

Note: What records you can access and what actions you can take on them depends on the privileges assigned to the user you are logged in as.

Creating a record

Creating a record is done using a POST-request. The content of your request should a json-document with properties corresponding to the attributes and relations of the associated model.

POST https://apps.appivo.com/api/app/MyApp/model/Car/record

Content-type: application/json
Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

{
   "make": "Audi"
   "model": "R8",
   "licenseno": "ABC123"
}

A successful response will have a body containing your record with the system attributes populated – as the id for instance.

Note: You can also pass an array of records and thereby creating many records all in one go.

Updating a record

To update an existing record you issue a PUT-request to the records unique URL. The body of your request must hold a JSON-document describing the requested state of the record.

Note: You must pass the correct current version of the record. The current version is held in the system-attribute called ‘ver’, failing to do so or passing an out of date version will cause the request to fail since MVCC is enforced.

PUT https://apps.appivo.com/api/app/MyApp/model/Car/record/17184cc413404a2594fbba2c00000001

Content-type: application/json
Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

{
   "id": "17184cc413404a2594fbba2c00000001",
   "ver": 0,
   "make": "Audi"
   "model": "R8",
   "licenseno": "ABC124"
}

Deleting a record

To delete a record you simple issue a DELETE-request to the records unique URL.

DELETE https://apps.appivo.com/api/app/MyApp/model/Car/record/17184cc413404a2594fbba2c00000001

Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

Get all records

To get all records of a model you can issue a GET request as below. It will return a JSON-array with all the records.

GET https://apps.appivo.com/api/app/MyApp/model/Car/record/

Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

Get a specific record

To get a specific record you issue a GET-request to the records unique URL, the one including the ID.

GET https://apps.appivo.com/api/app/MyApp/model/Car/record/17184cc413404a2594fbba2c00000001

Authorization: Bearer eyJraWQiOiJYbmdiVXszakxoRWQ5NDd1cUUwTiIsImFsZyI4IlJTnTEyIn0.eyJzdWIiOiIxNzFjMDVlYT...

If the record exists and is accessible you will get a 200-response with a JSON-document representing the record.

Query API

<TBD>