API Dokumentation

URLs & Version

API access under the following URLs:

• Staging: https://api.portagon-staging.de

• Production: https://api.portagon.io

Only use the HTTPS version of these URLs!

Versioning is handled over the URL as well, append  /v1 for current Version 1. See following API references for this version.

Authentication

The API uses authorization by token. You will get the tokens for the different enivornments from one of our project managers or you will find it in our admin panel.

Authorization: Token token=your-token-here

Wrong or missing tokens will raise  HTTP 401 Unauthorized.

curl "/api_endpoint_here"
  -H "Authorization: Token token=your-token-here"

Formats

The API accepts only  json and answers only with json. To ensure that and to send required formats always include

Accept: application/json

Content-Type: application/json

in your request header!

curl "/api_endpoint_here"
  -H "Authorization: Token token=your-token-here"
  -H "Accept: application/json"
  -H "Content-Type: application/json"

Pagination, Sorting, Filters

Pagination

We paginate the API results to ensure that you do not ask for  too much information by accident and so slow down results.

Some basics

• The global default for the number of entries beeing returned “per page” is currently 25.

• The maximum is currently set to 100.

• You can specify and own limit my adding an “limit” parameter in the GET URL (up to the specified maximum)

• It may occur that some endpoints have another default number of entries returned or changed maximum limits, you will find these information in the details for the specific API endpoint.

<http://api.portagon.io/v1/endpoint?page=1>; rel="first",
<http://api.portagon.io/v1/endpoint?page=6>; rel="last",
<http://api.portagon.io/v1/endpoint?page=4>; rel="next",
<http://api.portagon.io/v1/endpoint?page=2>; rel="prev"

Information about pagination will be shown in the Link header of the API call.

You can see an example on the right. In this API call you currently would be on  .../endpoint?page=3. Change the page paramter for your navigation. You should only use the Links provided in the header and not “guess” those.

If there is no Link header present in the API answer, no pagination is used due to a low number of entries.

Change the number of entries received

By passing the  limit parameter, you can tell the API how many entries you want per page to return, up to the maximum.

.../endpoint?limit=50

Sorting

All entries are by default sorted by  created_at: asc.

You can pass the  sort parameter to change the sorting of the results to your need.

.../endpoint?sort=name for ascending sorting

.../endpoint?sort=-name add an - to use descending sorting

Filters

Currently our API does not support any filtering or searching in the entries, we prefer you fetch all entries and do searching according to your needs in your own systems - please let us know if that feature would be usefull for you.

Information & Tips

Here you find some additional information for using our API.

JSON numbers

All attributes representing currencies/money (mostly only EUR) are BigDecimals in our system. To eliminate any loss of precision those  are via the API not issued as JSON Number but as JSON String. You can than parse the value according to your systems.

A BigDecimal would be naturally represented as a JSON number. Most libraries, however, parse non-integer JSON numbers directly as floats. Clients using those libraries would get in general a wrong number and no way to recover other than manually inspecting the string with the JSON code itself.

That’s why a JSON string is returned. The JSON literal is not numeric, but if the other end knows by contract that the data is supposed to be a BigDecimal, it still has the chance to post-process the string and get the real value.

Errors

This API uses the following error codes: