Our API specifies four key functionalities, each one has a different request method. Each request method has some standard functionalities you can use, which will be described below. Not every endpoint may implement all of those functions, for more information on what you can do with each endpoint, go here.
Searching
Requests can be made to search and retrieve data. These functionalities utilize the same API endpoint, but are followed by search/. These requests should be made with a POST method. This allows you to use filters to query large amounts of resources from our database.
Fields
To get data from an endpoint, you need to specify what fields you want to retrieve. By default, when you don’t specify anything, you’ll get a 400 Bad Request error. To get fields, you need to add the “fields” parameter to your request body. This must be a list of strings which specify what fields to get. What fields you can get is specified in the documentation for that endpoint. Including an incorrect field in your request results in a 400 Bad Request error.
By getting only the fields you need to get, your requests can be processed faster and requires less bandwidth on your side and our side.
Filters
Filters can be included in your request to narrow down your search, this can be useful for only getting games with certain tags. To filter your search, you should include “filters” in your request body, this must be a dictionary. The key of the dictionary is what field you want to search and the value is what you want to filter on.
To apply a filter, specify which field you want to filter on in a dictionary as a key. You can find which fields are available in the documentation for an endpoint, you can filter on any of the fields you can retrieve.
By specifying the value for a filter as a list, we automatically check if the field contains any of those values, if it does, it will be included in the output. An example would be the following:
“tags_list”: [“Adventure”, “Action”]
This will get all games that are either an adventure game or an action game. This is a case-sensitive operation.
Likewise, when you specify a string as the value, we automatically process that as a case-insensitive LIKE query. We return any result that contains the specified string, regardless of case. Any other value will be evaluated as an exact match.
Limiting data
By default, we only return the first 300 results, this is done to prevent excessive queries and accidentally getting a lot of data. We do not actually limit you in your request size, so if you need to get a lot of data, you can specify a higher result limit like 999999 to get all data. This may in some cases result in a 408 Request Timeout or 504 Gateway Timeout, so please be aware of that.
To change the range of data to get, you can use two parameters in your request “offset” and “limit”. Offset can be used to change the start value and therefore allows you to paginate the results. The limit specifies how many results to actually return, as mentioned before, by default this is 300, but can be increased and decreased as needed.
Response bodies of a GET request always contain the “total” field, this is the total number of objects that would be retrieved if there were no limit in place. “offset” and “limit” are also included in the response body, to make it easier to know what you just queried. If “offset” is larger than “total”, the “result” field will be an empty list, as there is no more data.
Response body
The response body of the GET method always returns the “message” and “status” fields in addition to the following fields:
- “total”: The total number of objects that would be retrieved without any limit.
- “offset”: The starting index of the retrieved records.
- “limit”: The maximum number of records returned.
- “result”: A list of dictionaries containing the selected fields.
Creating
POST requests can be used to create new objects, like users and permission groups. To create a new object, you need to specify some values, these values need to be included in the request body as “values” and this must be a dictionary. What values are required and which are optional can be found in the documentation for that specific endpoint.
You can also create relationships by using the ID field of a foreign object. For example, when you create a user, you can add a list of user group IDs in the “user_groups” field of the “values” dictionary to add the user to the specified user groups. This can save time when creating large amounts of users.
Responses of POST requests will always contain the newly created object in the “result” as a dictionary. This is useful when you need to edit the object later, add relationships or want to log what has happened already.
Response body
The response body of the POST method always returns the “message” and “status” fields. Additionally, POST requests also return a “result” field. This result is a dictionary representing the object that was just created. This includes all fields available in that endpoint.
Updating
The PUT method can be used to update an existing object. You need to specify which object to update by appending the “id” to the endpoint, an example could look like https://app.steamdatasuite.com/api/user/1234/, where 1234 is the “id“. Then, similarly to the POST request, you need to specify which values to update in the “values” field. This is a key-value mapping of what value should be assigned to which field.
If a field is not specified in the “values” field, it is not updated. If it is mentioned, then the data in that field will be overwritten. This also goes for relationships with foreign objects. For example, when you update a user and specify the “user_groups” parameter as an empty list, all old relationships will be removed, and the user would not be assigned to any groups anymore. This is done to make the API idempotent, so it doesn’t change anything when the same request is sent twice.
Invalid ID parameters cause a 404 Not Found error.
Response body
The response body of the PUT method always returns the “message” and “status” fields. Additionally, PUT requests also return a “result” field. This result is a dictionary representing the object that was updated. This includes all fields available in that endpoint. This is a representation of the object after it has been updated.
Deleting
Finally, the DELETE method can be used to delete an object. This can, for example, be a user or a user group, you need to specify the “id” in the URL. As an example, a DELETE request to https://app.steamdatasuite.com/api/user/1234/ will delete the user with id 1234. The deleted object is then returned in the “result” field of the response body.
Invalid ID parameters cause a 404 Not Found error.
Response body
The response body of the DELETE method always returns the “message” and “status” fields. Additionally, DELETE requests also return a “result” field. This result is a dictionary representing the object that was removed. This includes all fields available in that endpoint. This is a representation of the object before it was removed.