Universe API v1

Welcome to the API documentation for all of the endpoints for Universe.

Here, you will find information on the following endpoints:

General Specifications

Host

This is the primary host of the API paths: https://services.sparkart.net/api/v1

Requests/Responses

All requests need to be submitted in JSON format and all responses will be returned in JSON. The HTTP response code will always be a 200 Success regardless of the status.

Cross-Site Requests

We are using CORS headers in order to use this API across domains. Adding trusted domains to your fanclub can be done from Sparkart Tools:

NOTE: For browsers that do not support CORS headers, we default to JSONP instead.

Current Customer

Throughout these documents you'll notice the term current customer being used. current customer is referring to the currently logged in customer whose ID is saved in the session. Almost all endpoints in this API will require a current customer to be set in order to get the desired responses. If the current customer has not both registered and confirmed their email they will be in a logged out state. API responses for customers in this state will look like the following:

{
    "status": "error",
    "messages": ["Please log in to access your online benefits."]
}

Authentication

All endpoints, both GET and POST actions, require an API key (key parameter) to be passed in with the request. Your API key is unique to your fanclub and can be found under the Settings tab from Sparkart Tools.

Error Handling

Since all endpoints respond with a 200 Success, you will need to inspect the actual JSON response body to get the status of the response.

Status Response
success ok
failure error

Almost all errors responses will be accompanied by an array of error messages

Examples

GET /some_endpoint?key=YOUR_API_KEY

As stated above, you must include key=YOUR_API_KEY in every request. Otherwise you will get the failure response every time.

Request

Name Type Description
key string [Required] The API key associated with your fanclub

Responses

HTTP Status Code: 200 Success

Success: With a valid API key
{
    "status": "ok",
    "content-type": "Your desired content"
}
Failure: With an invalid API key
{
    "status": "error",
    "messages": [
        "Please use a valid API Key."
    ]
}
Failure: API error
{
    "status": "error",
    "messages": [
        "An error has occurred, please try again later."
    ]
}

Failure: 404 Not found

HTTP Status Code: 404 NotFound

{
    "status": "error",
    "messages": [
        "The requested resource was not found on this server."
    ]
}

Accessing the API without a Browser

You will need a valid session cookie in order for the end point to find the current customer and properly scope the response to your request.

Curl Example

This logs in the user and saves a session cookie in a file named services_cookies.

curl -c services_cookies -H "Content-Type: application/json" -d '{"email": "example@user.com", "password": "example"}' 'https://services.sparkart.net/api/v1/login?key=ValidAPIKey'

This uses the session cookie stored in services_cookies in a request.

curl -b services_cookies -H "Content-Type: application/json" -d '{"order":"DESC"}' -G 'https://services.sparkart.net/api/v1/orders?key=ValidAPIKey'