Overview

This document describes the composition of resources of BOS REST Web API v1. For the details about using this service, please refer to https://sandbox.api.friendlysky.com/v1/swagger-ui.html. If you have any problem, request or suggestion, please email to [email protected].

1. Version
2. Schema
3. Authentication
4. Parameters
5. Client errors
6. HTTP verbs
7. Pagination
8. Rate limiting
9. Cross origin resource sharing
10. Timezones
11. Embed field

Version

The current API version is v1. Please specify the API version in the URL.

Schema

The Web API service is all accessed with HTTPS and comes from https://api.friendlysky.com/v1. All data is sent and received as JSON.

For sandbox environment, refer to https://sandbox.api.friendlysky.com/v1.

curl -i -H “Authorization: Bearer {authorization token}” https://URL/v1/main-events/
HTTP/1.1 200
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 59
X-Total-Count: 10
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Vary: Accept-Encoding
Date: Fri, 13 Jul 2018 10:06:26 GMT

In most cases, null and empty string are included individually, and they will not be omitted.
All Dates follows ISO 8601 format:

YYYY-MM-DDTHH:MM:SS

It does not support changing the time zone in the current API version. The event time represents the current local time of game starting.

Authentication

If you would like to authenticate through Bos REST Web API, please contact us to get authorization token. You can contact us by email [email protected].

Authorization token (sent in a header)

Bearer {authorization token}” https://URL/v1/main-events/

Failed authenticate

No authorization or authenticating with invalid credentials will return 401 Unauthorized:

curl -i -H “Authorization: Bearer {invalid authorization token}” https://URL/v1/main-events/
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials"
}

Parameters

There are optional parameters in many API methods. For GET requests, parameters can be passed as an HTTP query string parameter except for that specified as a segment in the path.

curl -i -H “Authorization: authorization token” https://URL/v1/main-events?embed=description

In this example, the ‘v1’ and ‘main-events’ values are the parameters in the path while :embed is passed in the query string.

Client errors

Client error happens possibly when API server receives request:
Sending invalid fields will result in a 422 Unprocessable Entity response.

curl -i -H “Authorization: authorization token” https://URL/v1/main-events?name=test
HTTP/1.1 422 Unprocessable Entity
{
    "message": "Validation Failed",
    "errors": [
        {
            "field": "name",
            "message": "name can not be test"
        }
    ]
}

There are field properties and error messages in error objects so that your client can know what the problem is.

HTTP verbs

Where possible, Bos REST API strives to use appropriate HTTP verbs for each action.

Pagination

By default, requests which return numerous items will be paginated to 100 items. You can go to a specific page with the ?page parameter. Besides, you can set a custom page size up to 500 with the ?per_page parameter too. Note that if you set page size over 500, it will only show 500 items.

As a rule, page numbering is 1-based and it will return the first page without the ?page parameter. In addition, the page with the ?page<1 parameter will show the same items as the page with the ?page=1 parameter.

It will show total number of items in the returned HTTP headers: X-Total-Count of any API request as follows:

curl -i https://URL/v1/main-events
X-Total-Count: 10

Link header

The header includes pagination information:

link: 
<https://URL/v1/main-events?page=1&per_page=2>;rel="first",
<https://URL/v1/main-events?page=1&per_page=2>;rel="prev",
<https://URL/v1/main-events?page=3&per_page=2>;rel="next",
<https://URL/v1/main-events?page=5&per_page=2>;rel="last"

One or more Hypermedia link relations exist in this link response header and some of which may need enlarging as URI templates.

The rel values might be as follows:

As a rule, the first page will only show next and last. In contrast, the last page will only show first and prev.
It will show all kind of rel in the middle pages.

Rate limiting

Basically, you can create up to 1200 requests an hour for API requests. The rate limiting will be changed by different types of services.
Note that your current rate limit status will be showed in the returned HTTP headers of any API request:

curl -i https://URL/v1/main-events
X-RateLimit-Limit:1200
X-RateLimit-Remaining:1196
X-RateLimit-Reset:3543

The API will return a HTTP 429 “Too many requests” response code when an service exceeds the maximum request quota.

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2422
{
   "message": "Too many requests"
}

Cross origin resource sharing

The API supports AJAX requests which are Cross Origin Resource Sharing (CORS) no matter where the origin is. You may read html5security – CrossOriginRequestSecurity.wiki, CORS W3C Recommendation.

Timezones

Embed field

For reducing unnecessary data transfers, it must use embed as the query parameter to get the additional details.
The following is an instance of using embed as the query parameter and description as the query parameter value:

curl -i https://URL/v1/main-events?embed=description
{
"mainEventId": "Bpp",
"name": "Monster Jam World Finals XIX",
"currency": "USD",
"description": "<p><strong>Monster Jam World Finals XIX</strong> returns to <strong>Sam Boyd Stadium</strong> on <strong>March 23-24</strong> featuring the top 32 Monster Jam trucks and drivers competing for the coveted titles of Racing World Champion and Freestyle World Champion.</p>"
}

It will return default field value without using embed as the query parameter.

curl -i https://URL/v1/main-events
{
"mainEventId": "Bpp",
"name": "Monster Jam World Finals XIX",
"currency": "USD"
}

For more details about the possible query parameter value, refer to https://sandbox.api.friendlysky.com/v1/swagger-ui.html.