Wiki
Clone wikiAPI-2.0 / General_notes
API URLs
- development (if running locally): http://<tenant>.fuf.me:8888/
- testing: https://<tenant>.l27.co/v1/
- production: https://<tenant>.launch27.com/v1/
Authentication
Most API endpoints require authentication in the form of Authorization
HTTP header. Backend support two forms of authentication: JWT and token based (legacy).
JWT
JWT is returned as bearer
field in the Login response JSON. To use JWT authentication, provide Authorization
header in the form "Bearer <JWT data>". Curl example:
curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImxpbGx5QGt1bmRlLmluZm8iLCJzaW5nbGVfYWNjZXNzX3Rva2VuIjoiZW4zcm1PekJKczZtb2VSTmx3cUsiLCJleHAiOjE0OTc5Nzk3NDUsImlzcyI6IkxhdW5jaDI3In0.DrDR4wYoj0LRDQ4tu8yKAJU-FqTEgzcy8wqwego9SGg' ...
Token based authentication (legacy. is not available starting from March 1st, 2023)
To use token based auth, provide Authorization
header in the form "email:token" where token
is a single_access_token
returned by Login request. Curl example:
curl -H 'Authorization: user@email.com:U3BMqhPkzzF0unZd1Qay' ...
Dates and datetimes format
Unless otherwise specified, all datetimes are returned in UTC and in ISO 8601 format. Unless otherwise specified, all incoming datetimes are interpreted in client's timezone. Examples:
2015-01-31
- exampledate
parameter for Get spots (will be parsed as Jan 31 2015 in client's TZ)2015-01-31T14:30
- example bookingservice_date
parameter for Create booking (will be parsed as Jan 31 2015 2:30pm in client's TZ)
Rate limiting
Read and write API requests are separately rate limited and the current limits are returned in each response headers. For example these response headers:
x-rate-limit-read-limit:30 x-rate-limit-read-ttl:500ms x-rate-limit-write-limit:10 x-rate-limit-write-ttl:500ms
mean that we allow a max sustained rate of 2 reqs/second for both reads and writes with bursts up to 30 reqs for reads and 10 reqs for writes. These limits are per client IP address. The limiter uses https://en.wikipedia.org/wiki/Token_bucket algo, that Wikipedia article has pretty good description how it works and how actual limits depend on sustained activity.
Errors
- 400 Bad Request
Returned if POST/PUT request expected JSON but request body was empty. The response will have 'text/plain' content type with "Bad Request" body. Also returned if submitted JSON is invalid, in this case response will contain parser error.
- 401 Unauthorized
Returned if neither Authorization
header nor user_credentials
cookie were found, or user credentials were invalid.
- 403 Forbidden
Returned if requested feature (f.i. Giftcards API) is not available on current client plan.
- 406 Not Acceptable
Returned if POST/PUT/DELETE request fails some precondition checks. The response will have 'text/plain' content type and response body can be a simple "Not Acceptable" string but usually will contain more descriptive message.
- 415 Unsupported Media Type
Returned if POST/PUT/DELETE request is missing Content-Type:application/json
header.
- 422 Unprocessable Entity
Returned if POST/PUT request fails JSON schema or data validation checks. The server responds with JSON describing validation error(s) details. Here's an example response to the login request with an empty password:
{ "password":[{ "type":"string_gte", "message":"password: String length must be greater than or equal to 1", "description":"String length must be greater than or equal to 1", "value":"", "details":{ "field":"password", "min":1 } }] }
- 429 Too Many Requests
Returned if request rate exceeds rate limit.
Updated