Fetching Objects

Fetching Objects

Each object type will have a fetch method in that object's namespace.  The fetch method takes an indentifier for that object and returns a json representation of that object.  NULL is returned if no object exists with that identifier.  The following fetch methods are supported

• application.fetch
• key.fetch
• member.fetch
• role.fetch
• service.fetch

Primary Identifier

Each object has a primary identifier consisting of a single field which can be used to refer to that object or to find that object.  That field may be an integer field in some cases or a string field in other cases. 

The primary identifier can be passed as the parameter to the fetch method to specify which object to return.

Calling the fetch method

Here is an example request calling the fetch method

A JSON-RPC Request for calling the member fetch method

{
    "method": "member.fetch",
    "params": ["example_username"],
    "id": 1
}

The JSON-RPC Response

{
    "result": {
        "created": "2009-12-12T01:05:55Z",
        "updated": "2009-12-12T01:05:55Z",
        "username": "example_username",
        "email": "joe@example.com",
        "display_name": "Joe P. User",
        "uri": "",
        "blog": "",
        "im": "",
        "imsvc": "",
        "phone": "",
        "company": "",
        "address1": "",
        "address2": "",
        "locality": "",
        "region": "",
        "postal_code": "",
        "country_code": "",
        "first_name": "",
        "last_name": "",
        "registration_ipaddr": "",
        "area_status": "waiting",
        "external_id": "",
        "passwd_new": "",
        "object_type": "member"
    },
    "error": null,
    "id": 1
}

Object Not Found

Here is an example request calling the fetch method for an object which does not exist.

A JSON-RPC Request for calling the member fetch method

{
    "method": "member.fetch",
    "params": ["example_user_name_does_not_exist"],
    "id": 1
}

The JSON-RPC Response

{
    "result": null,
    "error": null,
    "id": 1
}

Alternative Object Identifier Syntax

Another syntax is available for specifying objects. Instead passing a simple primary identifier, you can pass a json object that consists of the field name of the primary identifier and the value you want to retrieve.  Here is is an example of a request using this syntax.  The response will be the same as the previous example.

A JSON-RPC Request for calling the member fetch method using the alternative object identifier syntax

{
    "method": "member.fetch",
    "params": [{"username":"example_username"}],
    "id": 1
}

Passing Whole Objects

Any extra fields passed using the alternaitve object identifier syntax will be ignored.  Thus, you can take the result of the fetch method or any other API method that returns an object and pass it back into the fetch method.  The fetch method will recognize the primary identifier and return a refreshed vesion of that object.  Here is an example in php using the MasheryApi class from the authentication example:

$member = $api->call('member.fetch', array('example_username'));
$refreshed = $api->call('member.fetch', array($member));

This feature is provided as a convenience allowing you to pass a previously fetched object back into the api to perform another operation on it.

Alternative Key Fetching

In addition to their primary integer identifier, key objects can also be identified by the combination of their service_key and apikey fields.  You can use this compound identifier with the alternative object identifier syntax to fetch keys.

A JSON-RPC Request for calling the key fetch method

{
    "method": "key.fetch",
    "params": [{"service_key":"example_service_key", "apikey":"example_apikey"}],
    "id": 1
}

The JSON-RPC Response

{
    "result": {
        "id": 339,
        "created": "2009-12-04T21:34:46Z",
        "updated": "2009-12-04T21:34:46Z",
        "service_key": "example_service_key",
        "apikey": "example_apikey",
        "username": "example_username",
        "status": "waiting",
        "rate_limit_ceiling": 0,
        "qps_limit_ceiling": 0,
        "rate_limit_exempt": false,
        "qps_limit_exempt": false,
        "required_referer": "",
        "secret": "",
        "limits": [
            {
                "period": "second",
                "source": "service",
                "ceiling": 2
            },
            {
                "period": "day",
                "source": "service",
                "ceiling": 5000
            }
        ],
        "object_type": "key"
    },
    "error": null,
    "id": 1
}