PRM_Software_AG
/
api-documentation
12
1
Fork 0
Code Issues 10 Pull Requests Activity

thoughts

This commit is contained in:
Nico Kroll 2024-05-27 06:23:23 +02:00
parent 6d620be849
commit 15dfdf22d7
1 changed files with 24 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
src/v2/README.md
View File

@ -23,22 +23,30 @@ 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
# Methods and resources
With each call you'll interact with ressources. We follow typical best practices in HTTP method and URI namings.
- GET /api/tyrepro/users -> Retrieve all customers
- GET /api/tyrepro/users/1 -> Retrieve data of customer 1
- GET /api/tyrepro/users/1/permissions -> Retrieve all permissions of customer 1
- POST /api/tyrepro/users -> Create a customer
- PATCH /api/tyrepro/users/1 -> Modify some data of customer 1
- DELETE /api/tyrepro/users/1 -> Delete customer 1
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 ressource, we allways use HTTP-POST-methods.
- POST /api/tyrepro/users/1/ban -> Ban customer 1
- POST /api/tyrepro/users/1/notify-gtc-violance -> Notifies customer 1 for a violation of the terms and conditions
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
@ -50,3 +58,8 @@ To apply non-CRUD-methods to a ressource, we allways use HTTP-POST-methods.
# 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.