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://example-store.de/
- https://onlineservices.prod.rz2.prm-ag.de/asd8s76df9/ - 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. With each call you'll interact with resources. We follow typical best practices in HTTP method and URI namings.
- GET /api/tyrepro/users -> Retrieve all customers - GET /api/core/Users -> Retrieve all customers
- GET /api/tyrepro/users/1 -> Retrieve data of customer 1 - GET /api/core/Users/1 -> Retrieve data of customer 1
- GET /api/tyrepro/users/1/permissions -> Retrieve all permissions of customer 1 - GET /api/core/Users/1/Permissions -> Retrieve all permissions of customer 1
- POST /api/tyrepro/users -> Create a customer - POST /api/core/Users -> Create a customer
- PATCH /api/tyrepro/users/1 -> Modify some data of customer 1 - PATCH /api/core/Users/1 -> Modify some data of customer 1
- DELETE /api/tyrepro/users/1 -> Delete customer 1 - DELETE /api/core/Users/1 -> Delete customer 1
To apply non-CRUD-methods to a ressource, we allways use HTTP-POST-methods. To apply non-CRUD-methods to a resource, we allways use HTTP-POST-methods.
- POST /api/tyrepro/users/1/ban -> Ban customer 1 - POST /api/core/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 - 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 # 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 # Errors
# Rate Limiting # Rate Limiting
@ -50,3 +58,8 @@ To apply non-CRUD-methods to a ressource, we allways use HTTP-POST-methods.
# Response Resolution # Response Resolution
# Caching # 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.