***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/<product>/...". This allows us to provide different views of the same resource depending on your use case and permissions.

## Domain

We as [PRM Software AG](https://prm-ag.de) 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](https://restfulapi.net/http-methods/).

- 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 <token>'. For use cases of temporary sharing or simplified backend to backend calls, you could also pass the access token as query parameter '?AuthorizationToken=<token>'. 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