From fae00c2a4cf7d6332ba17ca1e1c8631e02e57891 Mon Sep 17 00:00:00 2001 From: Nico Kroll Date: Mon, 24 Jun 2024 09:42:33 +0200 Subject: [PATCH] Further descriptions and development --- docs/README.md | 1 + src/v2/README.md | 68 +++++++++++++++++++++++++++++++++++------------- 2 files changed, 51 insertions(+), 18 deletions(-) diff --git a/docs/README.md b/docs/README.md index 07c137a..0491fba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,3 +25,4 @@ https://www.akamai.com/blog/security/rest-api-security-best-practices https://docs.hetzner.cloud/ https://opensource.zalando.com/restful-api-guidelines https://kubernetes.io/docs/reference/using-api/api-concepts +https://docs.stripe.com/api/prices diff --git a/src/v2/README.md b/src/v2/README.md index 00fa315..45d3a94 100644 --- a/src/v2/README.md +++ b/src/v2/README.md @@ -1,10 +1,10 @@ -*Currently under heavy development* +***Currently under heavy development*** -## Overview +# Overview Our API follows the REST-API-Principles. -# URI structure / Products +## URI structure / Products We will have a bunch of use cases. Some API consumers want to develop - an appointment making service @@ -15,7 +15,7 @@ We will have a bunch of use cases. Some API consumers want to develop Because of the variety of requirements, we offer different API products. The naming results to "/api//...". This allows us to provide different views of the same resource depending on your use case and permissions. -# Domain +## 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. @@ -23,9 +23,10 @@ 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 +## Methods and resources + +With each call you'll [interact with resources](https://restfulapi.net/http-methods/). -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 @@ -34,32 +35,63 @@ With each call you'll interact with resources. We follow typical best practices - 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.* +*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! +**The character casing of resource names is significant!** -# Authentication +## Authorization -*API keys* +### Static access tokens -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. +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.** -# Errors +### Access tokens by authentication -# Rate Limiting +In our authentication.yaml, you'll find endpoints to authenticate with some users credentials. -# Pagination +### Passing the parameters -# Sorting +The recommended way of passing the access token is within the HTTP-Header 'Authorization: Bearer '. For use cases of temporary sharing or simplified backend to backend calls, you could also pass the access token as query parameter '?AuthorizationToken='. Please be aware, that in a lot of libraries the request URI (including queryparameters) may get logged. -# Response Resolution +## Errors -# Caching +## Rate Limiting -## Open-API documentation +## 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