Pinch API

Pinch Media provides a REST based API to mirror almost all of the functionality available in the developer site. The API may be utilized to develop your own frontend to viewing your analytics data, provide widgets on your blog to showcase your application usage or much much more. If you have an interesting use for our API, let us know! We'd be happy to showcase it.

REST API Overview

REST (representational state transfer) APIs are accessed almost indentically to how a standard webbrowser would communicated with a website. All communication is completed through the HTTP protocol and is easily implementable in any programming language and can even be accessed directly through a webbrowser.

JSON Overview

All data passed into and retrieved out of the API is JSON format. JSON is a lightweight data format which has support in most programming languages. Read more about JSON on wikipedia or check out json.org for a JSON library for your language of choice.

API Requests

All API calls are quite similar and are made in the following format:

http://api.pinchmedia.com/<service>/<action>?api_key=<api key>&request=<parameters>

In the preceding URL the values surrounded by and including < and > must be replaced:

• <service> - This must be replaced with the service you are trying to access. A list of services can be found here.
• <action> - This must be replaced with the action of the service you are trying to access. View the documentation for the various services for descriptions of the method calls under each service.
• <api key> - This is the API key you are assigned to gain access to the API. You can find that here.
• <parameters> - This is the parameters to the method you are trying to call. This value is optional on a few calls and should be passed as a JSON string defined below. Parameters may also be passed as a POST variable as well instead of through the query string.

Sample Request with no parameters

The following URL would make a request to the application service and retrieve a list of applications associated with the users.

http://api.pinchmedia.com/application/retrieveApplications?api_key=<api key>

Sample Request with parameters

Parameters for API requests are pass through a JSON string in the request query string or POST variable. The following URL would make a request to the application service and retrieve the application data for the application code.

http://api.pinchmedia.com/application/retrieveApplication?api_key=<api key>&request={"applicationCode":"1234567890abcdef1234567890abcdef"}

API Responses

All responses from the API are returned as a JSON string in the same pattern:

{
  "response":"success",
  "data":{}
}

The response variable will either report "success" or "error". Depending on the value of that variable determines what data you should look for in the data object. If response is "error" then the data object will have an "error" variable which details the error you're experiencing. The following response shows an example of an error you may experience while using the API.

{
  "response":"error",
  "data":{
     "error":"Invalid request -- unknown method"
  }
}

The following response is an example of a successful request coming from the application service for the getApplications method.

{
  "response":"success",
  "data":{
    "applications":[
      {"code":"1234567890abcdef1234567890abcdef","name":"Application 1","is_admin":"1"},
      {"code":"fedcba0987654321fedcba0987654321","name":"Application 2","is_admin":"0"}
    ]
  }
}