Always Learning

RESTful APIs return data in responses containing a response header with the request status information and, depending on the verb performed, a response body containing data from the request.

  • GET - Returns HTTP headers and a response body containing the requested data.
  • POST - Returns HTTP headers, including a Location: header. Some APIs also return response body with the new data. See below.
  • PUT - Returns HTTP headers and usually a response body with updated object.
  • DELETE - Return only HTTP headers acknowledging the deletion.

See the specific API resource for a description of the supported responses for each request.

Response Body Format

The returned response body can be in either JSON (JavaScript Object Notation) or XML (eXtensible Markup Language). This can be determined by the optional {.format} parameter that is part of the URL. The {.format} parameter can have one of two values:

  • .json to return JSON
  • .xml to return XML

If no {.format} parameter is used, then the default format is JSON.

For example:

  • GET /me/upcomingevents – Returns data in JSON format.
  • GET /me/upcomingevents.xml – Returns data in XML format.
  • GET /me/upcomingevents.json – Returns data in JSON format.

POST Responses

When creating data using a POST request, the API will typically respond with a 201 HTTP status code (Created) and a header named "Location." The Location header identifies where to find the data that was just created. The typical workflow is to then issue a GET request on that value to verify the data, if desired. You can also do this to retrieve the new data and extract it's ID property. You shouldn't normally parse the Location value to find it's ID (see below).

Some APIs also return a response body containing the created data, but this is not guaranteed.

Response Links

Many routes return a response body that contain URLs that link to related information. The API response body includes a links property; for each link there are two values - href and rel.

  • The href value contains the direct link to the related information. You may use the direct link to make requests to the related information specified in the endpoint, but see the Important note below.
  • The rel value identifies the type of resources that href links to. It is provided for informational purposes only, and it's structure varies between APIs (some may be URNs, others are single words). This value is consistent throughout LearningStudio APIs for each type of resource but the actual value for each type may change from time to time (this is rare).

Important Note on Using Provided URLs

The URLs returned by the APIs in either the links, or the Location header from a POST response, should not be parsed to extract an object's ID. Officially, these URLs could change how they retrieve an object (e.g., by name instead of numeric ID), but an object's actual ID will never change. To get an  object's ID, you should GET the object using the full URL provided, and then extract the ID from the id property of that response.

Response Sort Order

Be aware that in RESTful APIs (including the LearningStudio APIs) do not guarantee the sort order for multi-object requests; results can be sorted differently from one request to the next. The exception is the API's documentation describes a specific sort order, and/or a query string parameter controls the sort order. Otherwise, you should not depend on the returned sort order for your processing unless you specify it in the request.

For example, the sortby query parameter can be used to control the sort order in some APIs:

  • GET /me/upcomingevents - The sort order of the response data is not controlled and may differ between calls.
  • GET /me/upcomingevents?sortby=when - The response data is sorted by the scheduled date of the event in chronological order.
  • GET /me/upcomingevents?sortby=title - The response data is sorted by the title of the event in ascending alphanumeric order.

Note: Not all APIs support sorting. Refer to the reference for each API.

5944 reads
Always Learning