Version 8

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/v1/openapi.yaml

@@ -331,6 +331,13 @@ paths:
       - "Customers"
       parameters:
       - $ref: "#/components/parameters/ResponseResolutionDepthParameter"
+      - name: "EMailAddressShouldBeUsedToCreateADefaultDocumentDespatch"
+        in: "query"
+        required: false
+        description: "The default - as in our ERP program TyrePro - is: NonCashReceiptDealsOnly, Invoices, CreditNotes and CustomerStorages will get delivered by E-Mail as normal PDF."
+        schema:
+          type: "boolean"
+          default: false
       requestBody:
         required: true
         content:
@@ -432,6 +439,13 @@ paths:
       - "Customers"
       description: "Finds similar accounts. The algorithm uses for example phonetic analysis and more to create the results."
       parameters:
+      - name: "GuidBranch"
+        in: "query"
+        required: true
+        schema:
+          type: "string"
+          default: null
+          example: "ebb89e89-8d25-809e-7814-c53b686ae164"
       - name: "Name1"
         in: "query"
         required: true
@@ -3954,13 +3968,13 @@ components:
             Amount:
               type: "number"
             SalesPriceNetSingle:
-              type: "string"
+              type: "number"
             SalesPriceGrossSingle:
-              type: "string"
+              type: "number"
             SalesPriceNetTotal:
-              type: "string"
+              type: "number"
             SalesPriceGrossTotal:
-              type: "string"
+              type: "number"
             Designation:
               type: "string"
             _HashValue:

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,30 +23,75 @@ 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.
+With each call you'll [interact with resources](https://restfulapi.net/http-methods/).
-- 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
 
-To apply non-CRUD-methods to a ressource, we allways use HTTP-POST-methods.
+- GET /api/core/Users -> Retrieve all customers
-- POST /api/tyrepro/users/1/ban -> Ban customer 1
+- GET /api/core/Users/1 -> Retrieve data of customer 1
-- POST /api/tyrepro/users/1/notify-gtc-violance -> Notifies customer 1 for a violation of the terms and conditions
+- 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
 
-# Authentication
+To apply non-CRUD-methods to a resource, we allways use HTTP-POST-methods.
 
-# Errors
+- 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
 
-# Rate Limiting
+*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.*
 
-# Pagination
+**The character casing of resource names is significant!**
 
-# Sorting
+## Authorization
 
-# Response Resolution
+### Static access tokens
 
-# Caching
+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.**
+
+### Access tokens by authentication
+
+In our authentication.yaml, you'll find endpoints to authenticate with some users credentials.
+
+### Passing the parameters
+
+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.
+
+## Errors
+
+## Rate Limiting
+
+## 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