The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes the Cisco Mobility Services Engine (MSE) Representational State Transfer (REST) API which is used to retrieve location information from the Mobility Services Engine.
Representational State Transfer (REST) is a design architecture that focuses on resources for a specific service and their representations. A resource representation is a key abstraction of information that corresponds to one specific managed element on a server. A client sends a request to a server element located at a Uniform Resource Identifier (URI) and performs operations with standard HTTPS methods, such as GET, POST, PUT, and DELETE. This provides a stateless communication between the client and server where each request acts independent of any other request and contains all necessary information to complete the request.
Mobility Services Engine provides a Representational State Transfer (REST) API. The REST API is useful for developers and administrators who aim to integrate the functionality of the MSE via the standard Hypertext Transfer Protocol (HTTPS).
The REST API is implemented as a Web service front-end component on the MSE gateway. The API allows applications to retrieve location data from the gateway using HTTP(s) GET requests using the URIs (Uniform Resource Identifier) specified in this document).
The data provided by the REST API can be formatted as XML (eXtensible Markup Language) and JSON (JavaScript Object Notation).
The benefits of the REST API are:
A REST resource is an abstraction of a piece of information, such as a single data record, a collection of records, or even dynamic real-time information. Each resource in the MSE REST API is identified by URI and is accessed using the standard HTTPS methods (GET, PUT, and DELETE).
This section contains the following topics:
The report data provided by the REST API can be formatted as XML and JSON. The data format is based on the values of the incoming HTTP accept header or the “outputType” query string parameter. If no specific data format type is found in the incoming request, then the REST API defaults the response data format and content-type to “text/csv”.
The response content-type may be specified using either the HTTP request “Accept” header or the “outputType” parameter. The “outputType” parameter has precedence over the “Accept” header. If neither the “outputType” parameter nor the “Accept” header (or if the Accept header found matches */*), the content-type defaults to “text/csv”.
The following “outputType” parameter values can be used:
When using the HTTP “Accept” header, the following can be used:
When the “Accept” header contains more than one accept type supported by the REST API, the following order of preference is followed:
Accept: text/xml, text/csv, application/json -- CSV is selected
Accept: application/json, text/csv -- CSV is selected
Accept: text/xml, application/json – JSON is selected
Accept: application/xml, text/csv, application/json – CSV is selected
Accept: text/html, */*, text/xml – XML is selected
Accept: text/html, */* – default to CSV due to the */*
Accept: text/html, image/jpeg, * -- default to CSV due to *
Accept: text/html, image/jpeg, text/plain -- 406 error is returned.
This Reports REST API defaults all the responses to the “UTF-8” charset encoding, irrespective of the requested charset sent.