HTTP API¶

Reference for the aedifion HTTP API.

Overview¶

The HTTP API allows accessing all services of the aedifion.io platform through a carefully designed RESTful interface. It can be accessed using a wide range of programming languages, libraries, tools and clients.

If you are using the aedifion.io cloud platform, the base URL of the HTTP API is

https://api.aedifion.io

If you are using a dedicated aedifion.io platform instance, the base URL of the HTTP API is

https://api.<REALM>.aedifion.io/

where <REALM> is specific to your dedicated platform.

Specifications¶

The HTTP API is completely specified in OpenAPI Specification Version 2 format.

• The specification can be downloaded from the API at https://api.aedifion.io/swagger.json.
• The specification can be visually inspected using the Swagger UI at https://api.aedifion.io/ui/.

Versioning¶

The HTTP API is versioned. The latest version is v2.

The version must be specified as a prefix to the path part of the URL.

https://api.aedifion.io/<VERSION>

E.g., the /user endpoint on API version v2 is located at https://api.aedifion.io/v2/user.

Note that https://api.aedifion.io/swagger.json and https://api.aedifion.io/ui/ always correspond to the latest version.

Older versions¶

• Version v1: Decomissioned in June 2019.

Design principles¶

The aedifion.io HTTP API is designed according to the following principles.

JSON encoding¶

All our HTTP API endpoints use the JSON format to encode content of request and response bodies. The JSON standard is widely used on the web and can be written and parsed in virtually any programming language as well as with a wide range of text and code editors.

HTTP methods¶

We make consistent use of HTTP methods:

• GET methods are used exclusively to query existing resources and will never trigger any modification of resources. In many cases, you can query single resources by providing a unique identifier or a list of resources of the same type. On success, they directly return the queried resource(s).
• POST methods are used exclusively to create new resources that previously did not exist, such as new users, projects, or tags. They return a Success object containing the created resource or an Error object with a message that indicates why creating the resource failed.
• PUT methods are used exclusively to modify existing resources and thus always require a unique identifier of the resource to modify. They return a Success object containing the modified resource or an Error object with a message that indicates why modifying the reference resource failed.
• DELETE methods are used exclusively to delete existing resources and thus always require a unique identifier of the resource to delete. They return a Success object containing the modified resource or an Error object with a message that indicates why modifying the reference resource failed.

HTTP status codes¶

The appropriate HTTP status code is used where possible, e.g.,

• 200 for successful retrieval, modification, and deletion of resources
• 201 for successful creation of resources
• 400 for bad requests that the user can correct
• 401 for access to non-existant or unauthorized resources
• 403 for valid and authorized requests that are forbidden due to other reasons
• 404 for access to non-existant resources where this does not leak information
• 5xx for internal server errors that are not due to and/or fixable by the user

Meaningful error messages¶

Upon error, an appropriate error message is returned that indicates what went wrong. The error message will be as informative as possible to help you fix the erroneous API call, but will deliberately spare out some details in order to protect privacy. E.g., error messages are formulated such that an unauthorized caller cannot distinguish a non-existant project from one that he/she does not have access to.

Transactional changes¶

Any API call that touches resources through creation, modification, or deletion, will either succeed as a whole or fail without any modification done. If any errors occurs during a creation, modification, or deletion of an existing resource, all changes made up to that point are rolled back. Viewing an API call as an atomic transaction, the transaction is either made completely or not at all.

Accessing the HTTP API¶

The API is accessed using HTTP which is one of the most widespread Internet standards today. Thus, you can use a wide range of tools and or programming languages to access it. The best choice depends on your use case and experience.

• Command line tools are probably the quickest way to issue simple HTTP requests. Adequate tools are already built in all Unix-like systems and may be downloaded for Windows. Of course, these tools do not know anything about the form of request parameters and responses so you will have to do all parsing yourself which quickly becomes unhandy for more complex requests.
• HTTP libraries are available for all established programming languages. At different levels of abstraction, they let you build, send, and receive HTTP requests and responses yourself. If you want fine-grained control about what is happening or would like to integrate aedifion.io's HTTP API into your own code, HTTP libraries are the best choice.
• Graphical REST clients are GUIs for HTTP that let you conveniently build, view, send, and parse HTTP requests and responses. If you just want to explore and try out the APIs, this is the best way.
• API clients can be automatically generated from our API specification for 40+ different programming languages, e.g., Python, Rust, C++, Go, Javascript, and many more. These API clients are, basically, high-level wrappers around standard HTTP libraries and relieve you of much of the boiler plate code for building requests, handling errors, and parsing responses.

Command line tools¶

Here is how to do a simple HTTP GET request including basic authentication using the two most popular command line tools for opening URLs.

curl https://api.aedifion.io/v2/user
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

wget https://api.aedifion.io/v2/user
    -O-
    --http-user=john.doe@aedifion.com
    --http-password=mys3cr3tp4ssw0rd

HTTP libraries¶

Here are examples in different programming languages for a simple HTTP GET request.

import requests

john = ("john.doe@aedifion.com", "mys3cr3tp4ssw0rd")
r = requests.get(f"https://api.aedifion.io/v2/user", auth=john)
print(f"{r.status_code} - {r.text}")

curl "https://api.aedifion.io/v2/user"
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Graphical REST clients¶

Swagger UI

The Swagger User Interface (UI) is a Javascript page that is auto-generated from our API specifications and allows you to interactively explore our APIs from within your browser without any additional software. We host it at https://api.aedifion.io/ui/

Postman

Postman is a software development tool that enables users to test calls to APIs via a GUI.

1. Download the Postman app from https://www.getpostman.com/downloads/
2. Start the app. You may skip the login.
3. Build your own story book of HTTP requests

Auto-generated API clients¶

Using the online Swagger Editor (or the Swagger Codegen desktop application), you can auto-generate API clients for 40+ different programming languages in a few steps:

1. Go to https://editor.swagger.io/
2. Download the the JSON specifications and paste it into the left-side editor field (convert to YAML if you want to).
3. On the top bar, click Generate Client and choose the desired language.
4. Download the ZIP Archive and unzip it.
5. Depending on the programming language, further customization steps might be necessary which we detail below.

# Default Base url
self.host = "https://api.aedifion.io"

#...

# Username for HTTP basic authentication
self.username = "john.doe@aedifion.com"
# Password for HTTP basic authentication
self.password = "mys3cr3tp4ssw0rd"

$ python3
>>> import swagger_client
>>> user_api = swagger_client.UserApi()
>>> r = user_api.get_user()
>>> print(r.user)
{'company_id': 1,
 'email': 'john.doe@aedifion.com',
 'first_name': 'John',
 'id': 1,
 'last_name': 'Doe'}
>>>

Further resources¶

• Explore our tutorials that show you how to, e.g., manage user, projects, and permission, or setup alarms, using the HTTP API.