3.8 KiB
Currently under heavy development
Overview
Our API follows the REST-API-Principles.
URI structure / Products
We will have a bunch of use cases. Some API consumers want to develop
- an appointment making service
- a shop integration with prices, stocks and more
- create and update orders
- update vehicle information
- many more cases...
Because of the variety of requirements, we offer different API products. The naming results to "/api//...". This allows us to provide different views of the same resource depending on your use case and permissions.
Domain
We as PRM Software AG offer you this API for our customers and act in that case as a service provider. For requesting the data of a trader, it is neccessary to get the permissions of each trader.
Each trader has it's own domain or a generated one by us. The base-URI could be:
Methods and resources
With each call you'll interact with resources.
- GET /api/core/Users -> Retrieve all customers
- GET /api/core/Users/1 -> Retrieve data of customer 1
- GET /api/core/Users/1/Permissions -> Retrieve all permissions of customer 1
- POST /api/core/Users -> Create a customer
- PATCH /api/core/Users/1 -> Modify some data of customer 1
- DELETE /api/core/Users/1 -> Delete customer 1
To apply non-CRUD-methods to a resource, we allways use HTTP-POST-methods.
- POST /api/core/Users/1/Ban -> Ban customer 1
- POST /api/core/Users/1/NotifyGtcViolance -> Notifies customer 1 for a violation of the terms and conditions
Yeah. In an ideal world we would use those verbs as HTTP-methods as well, but not all clients and servers support that functionality. And it's not common in the dev-society currently, therefore, we think, most developers would be confused.
The character casing of resource names is significant!
Authorization
Static access tokens
Within our ERP-system TyrePro, the trader is able to configurate static access tokens. Use static access tokens only, if you really trust the environment, where they are stored.
Access tokens by authentication
In our authentication.yaml, you'll find endpoints to authenticate with some users credentials.
Passing the parameters
The recommended way of passing the access token is within the HTTP-Header 'Authorization: Bearer '. For use cases of temporary sharing or simplified backend to backend calls, you could also pass the access token as query parameter '?AuthorizationToken='. Please be aware, that in a lot of libraries the request URI (including queryparameters) may get logged.
Errors
Rate Limiting
Pagination
Sorting
Response Resolution
Caching
Confirmation codes
some request require an explicit confirmation. There the server creates a confirmation code and a message and the client has to send the request again with the confirmation code. the code is temporary stored at server side.
Events
subscribe to events and get a post request on your side
Performance
response header notice
Open-API documentation
Because of all those general options, we use a minimal documentation style of our Open-API-yaml-files. Example: Even when you will not find the pagination-parameters in the yaml-file, you can use them. The usage of the minimal style will make it easier for you to see what exactly is part of the implementation and what is general. In a scenario of a full documentation the actual implementation details may be skipped in the complexity of general parameters.
A typical request flow
- Request entering
- URI normalization
- Ressource identification
- Authorization check
- Rate limit check
- Request processing
- Cache postprocessing