This API implements a RESTful approach to access and manipulate data. A REST API defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST.
Our API makes use of the GET (read), PUT (create), POST (updated), and DELETE (delete) HTTP verbs. Requests are made to their respective endpoints which are named after the specific object desired. To retrieve a stream, the "streams" endpoint would be called with the name of the stream (GET {url}/streams/<stream_name>). To retrieve all streams, no stream name would be given (GET {url}/streams/)
We have two main APIs that can be called, our main for most objects is located on api.scaleengine.net. While our file api is located on the file server jb-sestore.secdn.net. Make sure to check the objects documentation to verify you are calling the correct server.
Fields are the properties of an object and are included in the responses from their respective endpoints. Fields are defined by the follow attributes:
Parameters are additional data that may be required to fullfil the request, but are not returned in the response. Parameters should be sent as POST data.
Filters are GET parameters that are used to limit or modify
results found when retrieving objects. Generally, any
non-synthetic field can be used as filters.
Some objects may have special filters, known as "options",
that modify the results being returned. These filters must be
prefixed with option:. The files endpoint can take
a "recursive" option and would be requested as
option:recursive=2, assuming we want 2 levels
of directories to be searched.
For example:
https://username-sestore.secdn.net/v1/files/?type=file&option:recursive=2
The filters section of the object documentation is where you can find details on what filters are allowed and what values are permitted.
You can also prefix a GET parameter with a pipe | operator
to do a bitwise AND operation on an integer field. For eg:- |flags=4
will filter objects that return a non-zero value when doing a bitwise AND
operation with the value of the flags field. So, valid values of the flags field for
|flags=4 would be 4,5,6,7,12 etc.
Objects may have related information that can be accessed through different endpoints, these related objects are not returned by default. To retrieve relational data with the base object the "related" GET parameter is used.
The related parameter takes a comma separated list of objects to include in the response. See the response fields section below for details on the response format.
For example, streamfetches have are related to streams, so we can have the related stream object returned along with the streamfetch:
https://api.scaleengine.net/dev/v2/streamfetches/~1234?option:related=stream
There are also "children" objects. While a related object is a single item linked to the object in question, there may be multiple child items linked to a single item. Players are children of a stream, because you can have multiple players set up for a single stream. So we can get the child players of a stream:
https://api.scaleengine.net/dev/v2/streams/streamname?option:children=players
You can specify multiple child and/or related
objects at the same time. Either pass a comma
separated list of objects, i.e.
option:children=players,streamfetches
or send them as http array elements:
option:children[]=players&option:children[]=streamfetches
Responses from each endpoint will set a meaningful HTTP status code that be used to determine if the call was successful, unauthorized, or any other type of error that may have occured along with a generic message (see HTTP Status Codes page).
One or more of the following fields will be returned as json.
Upon success the data field will be set to the respective object based on the endpoint being called or an array of objects when a GET request is made without an ID. If an error occurs the data field will not be present.
When an object is retrieved using the "related" parameter, the related field will be added to the object. This field is an associative array with the object's type as the key containing an array of those objects.