Creating Objects

Each object that allows creation via the API will have a create method in that object's namespace.

• application.create
• key.create
• member.create
• role.create

The create method takes a JSON representation of the object to be created.  If a field is ommitted from the object passed, a default value will be used.

Some fields are required to be present in order to create an object. The object.describe method can be used to fetch the json schema description of that object.  Fields that are required during create will have a required attribute of true.

The create method will return a json representation of the object created upon success.  This new object has omitted fields filled in with default values and read only fields will be filled in.  This is the actual object that was created.

If the object specification passed was not correct, create may return an invalid object error.  Other errors may occur.

Calling the Create Method

Here is an example request calling the role.create method.  Role create is the simplest of the create methods.

A JSON-RPC Request for calling the create method

{
    "method": "role.create",
    "params": [{"name":"example_role_name"}],
    "id": 1
}

The JSON-RPC Response

{
    "result": {
        "id": 378,
        "created": "2009-12-02T23:46:49Z",
        "updated": "2009-12-02T23:46:49Z",
        "name": "example_role_name",
        "description": "",
        "is_assignable": true,
        "is_predefined": false,
        "object_type": "role"
    },
    "error": null,
    "id": 1
}

Validation Errors

If there is an error in the data passed, an invalid object error message will be returned.

A JSON-RPC Request for calling the create method

Here is an example request calling the role.create method, but with insufficient data.

{
    "method": "role.create",
    "params": [{}],
    "id": 1
}

The JSON-RPC Response

{
    "result": null,
    "error": {
        "message": "Invalid Object",
        "code": 1000,
        "data": [
            {
                "field": "name",
                "message": "This value is not allowed to be blank."
            }
        ]
    },
    "id": 1
}

Establishing Relationships

When two objects are related in a has many relationship, one side owns the other object.  That object can be said to belong to its owner.  An example of this in the Mashery API is the service object which can have many keys defined for that service.  A key can be owned by only one service.

It is possible to establish which object owns the object being created as part of the create method call.  This is done by using the alternative object identifier syntax.  An indicator of the object to establish a relationship with is passed in the field representing that relationship.

For some objects, it is required that ownership be established at create time.  For example, every key object belongs to a member and a service.

A JSON-RPC Request for calling the create method

Here is an example request calling the key.create method.  We choose a new api key and associate it with an existing service and member.

{
    "method": "key.create",
    "params": [
        {
            "apikey": "example_apikey",
            "service": {
                "service_key": "example_service_key" 
            },
            "member": {
                "username": "example_username" 
            } 
        } 
    ],
    "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
}

Copying Objects

Any extra fields passed will be ignored.  Thus, you can take the result of a fetch, or the result of a previous create and pass that back in to create a copy of that object.  You need only change values that must be unique.

// Read an existing member
$member = $api->call('member.fetch', array('example_username'));

// Change the name
$member->username = 'different_name';

// Create a copy of that user
$member_copy = $api->call('member.create', array($member));