api-documentation/src/v2

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:

• https://example-store.de/
• https://onlineservices.prod.rz2.prm-ag.de/asd8s76df9/

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

1. Request entering
2. URI normalization
3. Ressource identification
4. Authorization check
5. Rate limit check
6. Request processing
7. Cache postprocessing