RESTful API Introduction

A RESTful Interface sends a HTTP GET or POST to call exposed methods on a network, and receives an XML document in return.

The MDP (MySpace Developer Platform) provides a RESTful API that allows server-to-server requests to expose member information for installed members.

This API permits modification of member data if the member has granted the required access to the application, and exposes communication functionality for friend activities, messaging, bulletins, and application notifications.

The MySpace RESTful API adheres to the principles of REST architecture, and supports all HTTP verbs - GET, PUT, POST, DELETE, and HEAD.

Response formats should be as robust as possible. Resources default to Plain Old XML (POX), but this can be modified by using an extension on the resource such as .xml or .json.

Click here for more information about REST resources under the Reference section.

REST API Request Authentication

Every request to the API must be authenticated using a digital signing mechanism. This process involves identifying yourself to the API and then validating your identity by creating a digital signature. The digital signature uses specific elements from the request along with a shared secret value provided to you upon authentication. This digital signing mechanism is the standards-based OAuth specification.

Creating the base string

To sign the request, you must create a Signature Base String. This string is created by concatenating three percent-encoded parameters of the request using an ampersand as the delimiter. The parameters used to form the base string are:

1. The HTTP method of the request (GET, POST, PUT, etc.). This method must be in all uppercase.
2. The scheme, authority and path of the URL Request. The query string and fragment identifier are excluded. The scheme and authority must be in lowercase. The default port 80 must be excluded.
3. Normalize the Request Parameters

Do the following to normalize the parameters:

1. Gather the GET query parameters, the HTTP POST or PUT request body parameters and, if the Authorization header is used, the OAuth parameters in the Authorization header excluding the realm and oauth_signature
2. Sort the parameters primarily by name and secondarily by value
3. Concatenate the parameters in order and delimit as follows:
   • a. By name and value with an ‘='character delimited
   • b. By pairs with an ‘&' character delimiter

Creating the Signature

1. The text is the base string
2. The key is the concatenated values of the two parameters below:
• The Consumer Secret provided upon creation of the application
• An empty string ("").

REST Response Formats 

The REST API provides both XML and JSON response formats. The default response format is XML, but a "json" extension on the resource can request the JSON format. The following example requests a JSON response format by using the "json" extension: http://api.msappspace.com/users/23423.json. Without the "json" extension, the response format would default to XML. Some properties of XML and JSON response formats are provided below.

XML

XML is a language-independent API used to transfer data between the client and server sides of a web page. The response to an XML request can be an XML document, a text string, or a binary encoded string. Asynchronous XML fetches promote quicker UI responsiveness.

JSON

The JSON (JavaScript Object Notation) is a machine-readable data exchange format using conventions derived from the C family of programming languages. JSON is built on two universal data structures:

1. A collection of name/value pairs that can be represented as a user-defined object.
2. An ordered list of values that can be represented by an array. The JSON data separators are identical to those used by JavaScript engines to represent data structures such as strings and arrays, and this often provide for easier data access than what would be achieved with XML. Because JSON is less verbose than XML, it lacks certain properties that are available in the latter. For example, namespaces allowing identical pieces of information to be mixed in different contexts in XML are not available in JSON. Converting from XML to JSON can present challenges when distinguishing between the actual value of attributes and the text between tags because JSON assignments are done with colons.