sharee.bike-Wiki/3.-sharee.bike-API-description.md
2023-11-22 16:57:28 +00:00

3.1 KiB
Raw Blame History

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