From 15dfdf22d7a233d948dd9b920343f8e04d974f6f Mon Sep 17 00:00:00 2001 From: Nico Kroll Date: Mon, 27 May 2024 06:23:23 +0200 Subject: [PATCH] thoughts --- src/v2/README.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/src/v2/README.md b/src/v2/README.md index 1c176fa..00fa315 100644 --- a/src/v2/README.md +++ b/src/v2/README.md @@ -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.