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.
  
The following access parameters must be arranged: Consumer Key for the authentication of the client, Consumer Secret for the encryption and the hashing.
+
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.
Request
 
  
All requests must be directed to the "Mobile" API Connector of the according server:
+
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):
  
 
<pre>
 
<pre>
http://<server_address>vz.net/Api/Mobile/V1/<method>?<method_parameters><access_parameters>
+
http://<platformurl>/Api/Mobile/V1/<method>?<method_parameters><access_parameters>
 
</pre>
 
</pre>
  
 
Only requests methods are GET for read only method calls and POST for writing method calls.
 
Only requests methods are GET for read only method calls and POST for writing method calls.
Authentication
+
 
 +
=== 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.
 
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 ===
+
=== 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 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.

Revision as of 08:55, 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>
           }
       ]
}}