General notes

The ModelCentro API is the underlying interface for our official mobile app and our websites. It's the most direct way to access our public DB. This reference document is designed for those interested in integrating our platform or for those interested in exploring API features in detail.

API compatibility

This API will evolve. Future versions of this API may add new endpoints or parameters. In order to keep older clients working, the behavior and return value of APIs with given parameter values will not change from the currently documented behavior and return values, with two important exceptions: currently undocumented request parameters (whether they are actually ignored or not) may be given a specific meaning, and objects returned in responses may contain additional keys in the future. Thus, clients that want to be future-proof should avoid passing undocumented parameters (as they may cause different behavior in the future), and they should avoid strict checks on the keys of objects found in responses. For example, you should not consider a /content response invalid if it contains additional keys besides those currently documented below.

SSL only

We require that all requests are done over SSL.

UTF-8 encoding

Every string passed to and from the API needs to be UTF-8 encoded.

Date and time format

All dates in the API are strings in the following format: 2015-06-25. In code format, which can be used in all programming languages that support strftime or strptime: %Y-%m-%d. All timestamps in the API are strings in the following format: 2015-06-25 09:25:58. In code format, which can be used in all programming languages that support strftime or strptime: %Y-%m-%d %H:%M:%S.

Note, that we are working in CEST

Error handling

Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted. Error codes not listed here are in the API methods listed below.

Code	Description
400	Bad input parameter. Error message should indicate which one and why.
401	Bad token. This can happen if the system revoked an access token. To fix, you should re-authenticate.
403	Expired token. This can happen if the system expired an access token. To fix, you should re-authenticate.
404	Instance not found. This may indicate that you are trying to access unexisting or unallowed instance.
405	Request method not expected (generally should be GET).