Updating Objects

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

• application.update
• key.update
• member.update
• role.update

The update method takes a JSON representation of the object to be modified.  The object.describe method can be used to fetch the json schema description of that object.  This call will show which fields are available to update.  fields marked readonly and createonly will be ignored if passed in the update specification.  Fields that are omitted will not be changed.

The objecst specification must include the primary identifier for the object that is to be updated.  This is identical to the alternative object syntax form of the fetch method.  See Fetching Objects for more information on identifying objects.

The update method will return a full json representation of the object modified upon success.  This is the actual object after modification.

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

Calling the Update Method

Here is an example request calling the role.update method.  This call changes the name of an existing application.  The application is specified by the id parameter.  This example updates the application created in the example code from application.create.

A JSON-RPC Request for calling the update method

{
    "method": "application.update",
    "params": [
        {
            "id": 1234,
            "name": "new_application_name"
        }
    ],
    "id": 1
}

The JSON-RPC Response

{
    "result": {
        "id": 1234,
        "created": "2009-12-11T00:25:45Z",
        "updated": "2009-12-11T00:33:05Z",
        "username": "example_username",
        "name": "new_application_name",
        "description": "",
        "type": "",
        "commercial": false,
        "ads": false,
        "ads_system": "",
        "usage_model": "",
        "notes": "",
        "how_did_you_hear": "",
        "preferred_protocol": "",
        "preferred_output": "",
        "external_id": "",
        "uri": "",
        "status": "draft",
        "object_type": "application"
    },
    "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 update method

Here is an example request calling the application.update method, but with invalid data.

{
    "method": "application.update",
    "params": [
        {
            "id": 1234,
            "name": ""
        }
    ],
    "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
}

Object Not Found Errors

If the object could not be found, an object not found error object will be returned.

A JSON-RPC Request for calling the update method with an object that does not exist

{
    "method": "member.update",
    "params": [
        {
            "username": "i_dont_exist"
        }
    ],
    "id": 1
}

The JSON-RPC Response

{
    "result": null,
    "error": {
        "message": "Object \"member\" with \"username\" of \"i_dont_exist\" could not be found.",
        "code": 5000,
        "data": {
            "id_fields": [
                "username"
            ],
            "id_values": [
                "i_dont_exist"
            ],
            "object_type": "member"
        }
    },
    "id": 1
}

Changing Relationships

The update method may be used to change objects related to the specified object via a belongs to relationship.  Some relationships cannot be changed at all.  See the establishing relationhips section of Creating Objects for more information on related objects.