mirror of
https://gitlab.com/t6353/sharee.bike.wiki.git
synced 2024-11-16 07:16:33 +01:00
49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
## sharee.bike API description
|
||
Version 4.1.23.22
|
||
|
||
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:
|
||
- request=authentication
|
||
- request=authout
|
||
- request=stations_available
|
||
- request=user_bikes_occupied
|
||
- request=user_minianswer
|
||
|
||
The operator server (uri_operator) responsible for the rental process is used for:
|
||
- request=bikes_available
|
||
- request=booking_request
|
||
- request=booking_update
|
||
- request=user_feedback
|
||
|
||
**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**
|