Further descriptions and development

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

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/<product>/...". 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 <token>'. For use cases of temporary sharing or simplified backend to backend calls, you could also pass the access token as query parameter '?AuthorizationToken=<token>'. 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