Difference between revisions of "MAPI V1:Introducing"

From VZ Developer Wiki
Jump to: navigation, search
m (Created page with '=== 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. T…')
 
(No difference)

Revision as of 09:19, 6 May 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.

The following access parameters must be arranged: Consumer Key for the authentication of the client, Consumer Secret for the encryption and the hashing. Request

All requests must be directed to the "Mobile" API Connector of the according server:

http://<server_address>vz.net/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.

Response

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>
           }
       ]
}}