*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. We follow typical best practices in HTTP method and URI namings.
- 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 currently, therefore most developers would be confused.*

The character casing of resource names is significant!

# Authentication

*API keys*

Within TyrePro you can configurate API-Keys. They can have the scope of the tenant, a branch, a user or a customer (online user). The scope also determines the data provided by the endpoints.

# Errors

# Rate Limiting

# Pagination

# Sorting

# Response Resolution

# Caching

## 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.
