Difference between revisions of "MAPI V1:Introducing"

From VZ Developer Wiki
Jump to: navigation, search
 
Line 3: Line 3:
 
VZ mobile API is a HTTP-based REST Interface which is provided by studiVZ to allow external (mobile) applications access to functionality of VZ.net platforms.
 
VZ mobile API is a HTTP-based REST Interface which is provided by studiVZ to allow external (mobile) applications access to functionality of VZ.net platforms.
  
It is designed in the style of the OAuth 1.0 specification (we call it mAuth as it was intended to be used with mobile clients) but it can even be used with OAuth.
+
It is designed in the style of the [http://hueniverse.com/oauth/ OAuth 1.0 specification] (we call it mAuth as it was intended to be used with mobile clients) but it can even be used with OAuth.
  
 
All requests must be directed to our "Mobile" API Connector of the according plattform (i.e. www.studivz.net, www.meinvz.net or www.schuelervz.net):
 
All requests must be directed to our "Mobile" API Connector of the according plattform (i.e. www.studivz.net, www.meinvz.net or www.schuelervz.net):

Latest revision as of 09:11, 16 September 2010

General

VZ mobile API is a HTTP-based REST Interface which is provided by studiVZ to allow external (mobile) applications access to functionality of VZ.net platforms.

It is designed in the style of the OAuth 1.0 specification (we call it mAuth as it was intended to be used with mobile clients) but it can even be used with OAuth.

All requests must be directed to our "Mobile" API Connector of the according plattform (i.e. www.studivz.net, www.meinvz.net or www.schuelervz.net):

http://<platformurl>/Api/Mobile/V1/<method>?<method_parameters><access_parameters>

Only requests methods are GET for read only method calls and POST for writing method calls.

Authentication

In order to read or write users data all API calls must be authenticated. It means user must grant access to his resources on VZ.net site to the client application. There are two kinds of authentication, supported by the API. OAuth based authentication and special Auth version for mobile clients. See authentication section for detailed description.

Responses

The response of the request will be delievered in JSON format. The structure consists of the sections "meta" and "content". The "meta" section contains the metadata of the response and the return values of the corresponding API method are encapsulated in the "content" section.

The metadata contains the following blocks:

  • version - recent version of the API
  • nonce - random string (referred in the request and send back unmodified)
  • success - status flag (true when succesful / false at exceptions)
  • count - number of dataobjects, which are delivered
  • total - optional total number of objects for lists

Format:

Successful response format:

{"result":

 {
   "meta"    :
       {
           "version"   : <api_version:number>,
           "nonce"     : <request_nonce:string>,
           "success"   : true, // OK
           "count"     : <content_rows_number:number>
       },
   "content" : <content_data:string|number|boolean|array>,
}}

In case of error the "content" sections contains an errror-code and an exception-message will be delivered.

Exception response format:

{"result":

 {
   "meta"    :
       {
           "version"   : <api_version:number>,
           "nonce"     : <request_nonce:string>,
           "success"   : false, // Exception
           "count"     : 0
       },
   "content" :
       [
           {
           "code"    : <number>,
           "message" : <descriptive_string>
           }
       ]
}}