From 14a1362183711ce639ff276c85d0798237ff5116 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rainer=20G=C3=BCmpelein?= Date: Fri, 28 Jan 2022 10:53:23 +0000 Subject: [PATCH] Create sharee.bike API description --- sharee.bike-API-description.md | 38 ++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 sharee.bike-API-description.md diff --git a/sharee.bike-API-description.md b/sharee.bike-API-description.md new file mode 100644 index 0000000..a52be82 --- /dev/null +++ b/sharee.bike-API-description.md @@ -0,0 +1,38 @@ +## sharee.bike API description +Version 4.1.10.2 + +The document serves as a technical reference for the sharee.bike rental bike platform for rental bike client development. The rental bike management server COPRI serves as the backend system. + +### 1. Intro +The data exchange format is based on HTTP's REST methods. + +- COPRI expects the client-side https requests to be "urlencoded" (https post, https get). +- The server-side https responses are delivered by COPRI in JSON format. + +**Multi-operator rental bike booking system** implements a decentralized rental bike booking system across multiple sharee operator instances. Each operator instance is exclusively available to a rental bike operator for the administrative management of the operator rental bike data. The client-side user authentication takes place via the *primary COPRI-server (single-sign-on)*. Successful user authentication can be recognized by an *authcookie* of at least 30 characters in the JSON response. An empty *authcookie* means that the user is not authenticated. + +**Rental bike bookings** are only possible after successful user authentication. + +The primary server (uri_primary) is used for user authentication. During the "booking_request" rental bike, the operator server responsible for the rental process (uri_operator) is delivered in the rental bike JSON object. + +**encoding** UTF-8. All scalar JSON values ​​are delivered as data type "char" (text). + +**Glossary** +| table-column | value | description | +|--------------|-----------|------------------------------------------------------| +| Format | text>=8 | UTF-8 encoded characters with a character length >= 8 | +| Format | date time | ISO 8601 (YYYY-MM-DD hh:mm:ss) timestamp | +| Format | object | sub-datatype JSON Object | +| Format | array | datatype Array | +| Required | + | Field assignment mandatory | +| Required | o | Field assignment optional | + +The user authentication expects the following 4 parameters. +- user_id: `mail@example.tld` +- user_pw: `example-pw` +- hw_id: `unique-system-identifier` +- merchant_id: `your merchant id` (for id contact us) + +The *hw_id* with at least 16 characters must be unique. In live operation, the hw_id should be read from the client system (unique-system-identifier). After successful authentication, an *authcookie* is generated on the server side from the *authorization* parameters. +**Requests** in the context of rental bike bookings, a valid *authcookie* is always expected in REST, which authenticates the user after a successful login and authorizes him to use the system. +No prior user authentication is required to query the available stations and rental bikes. An *authcookie* with the *merchant_id* customer ID is expected as a minimum requirement. I.e. **authcookie=merchant_id**