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 - example date parameter for Get spots (will be parsed as Jan 31 2015 in client's TZ)
• 2015-01-31T14:30 - example booking service_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.