Requests

This is a detailed description of how to make requests to the ActionKit REST API.

Retrieving Resources with HTTP GET

Requesting a resource using GET will return a representation of the current state of the resource. Loading a URL in a web browser is a simple way to try a GET request.

GET responses may return the following status codes:

Response Status Code Description
200 OK The request was successful and the response body contains the representation requested.
301 MOVED PERMANENTLY A common redirect response to the canonical URI for the representation of the resource. You can GET the representation at the URI in the Location response header.
302 FOUND A common redirect response; you can GET the representation at the URI in the Location response header.
304 NOT MODIFIED Your client's cached version of the representation is still up to date.
401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to access the resource.
404 NOT FOUND Resource not found.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 SERVER ERROR We couldn't return the representation due to an internal server error.
503 SERVICE UNAVAILABLE We are temporarily unable to return the representation. Please wait for a bit and try again.

Here's a GET for an object that doesn't exist (at least, on this server!). We get back a 404 status code.

$ curl -i -u user:password https://docs.actionkit.com/rest/v1/user/111111/
HTTP/1.1 404 NOT FOUND
Date: Fri, 16 Mar 2012 17:31:33 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: text/html; charset=utf-8
Content-Length: 0

Here's a GET for an object that does exist, the Main email list.

$ curl -i -u user:password https://docs.actionkit.com/rest/v1/list/1/
HTTP/1.1 200 OK
Date: Fri, 16 Mar 2012 17:33:28 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "name": "Main email list",
    "created_at": "2012-03-14T09:06:01",
    "updated_at": "2012-03-14T09:06:01",
    "is_default": false,
    "hidden": false,
    "resource_uri": "/rest/v1/list/1/"
}

Resources can be either details about a single resource or lists of resources. We tend to use the vocabulary of detail or list endpoints. Requesting a list resource follows the same rules as the examples above, but you get back a data structure with metadata about the list. There are more details in the responses section of the REST API Overview.

$ curl -i -u user:password https://docs.actionkit.com/rest/v1/list/
HTTP/1.1 200 OK
Date: Fri, 16 Mar 2012 17:33:28 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "created_at": "2009-09-02T00:44:40",
            "hidden": false,
            "id": 1,
            "is_default": true,
            "name": "My List",
            "resource_uri": "/rest/v1/list/1/",
            "updated_at": "2013-04-09T02:44:11"
        },
        {
            "created_at": "2009-10-27T22:14:48",
            "hidden": false,
            "id": 2,
            "is_default": false,
            "name": "E-newsletter",
            "resource_uri": "/rest/v1/list/2/",
            "updated_at": "2010-06-14T18:56:07"
        }
    ]
}

The list resource returns two top-level data structures, meta and objects. Objects is a paginated list of, well cough, objects. Meta contains information about the total matching set and how to get the next set of results.

Creating or Updating Resources with POST, PUT, and PATCH

You can create or update resources by making a POST, PATCH, or PUT request. POSTing to a collection will add a new resource. PATCHing and PUTing to an existing object resource will update that resource.

Be sure to consult the schema for your desired endpoint at /rest/v1/ to determine which methods are available.

For example, to create a new user, we POST to the user collection:

$ curl -X POST -i -u user:password -H 'Content-type: application/json' -H 'Accept: application/json' -d '{ "email": "happynewuser@example.com" }' https://docs.actionkit.com/rest/v1/user/
HTTP/1.1 201 CREATED
Date: Mon, 19 Mar 2012 14:20:50 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: text/html; charset=utf-8
Location: https://docs.actionkit.com/rest/v1/user/1026/
Transfer-Encoding: chunked

Note

How did we know where the user collection was found? We looked at the root resource and looked for the 'list_endpoint' under 'user'.

The representation of the new user is now available at the URI in the Location header:

$ curl -i -u user:password https://docs.actionkit.com/rest/v1/user/1026/
HTTP/1.1 200 OK
Date: Mon, 19 Mar 2012 14:35:31 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "last_name": "",
    "suffix": "",
    "phones": [],
    "updated_at": "2012-03-19T14:20:50",
    "actions": [],
    "prefix": "",
    "orders": [],
    "city": "",
    "first_name": "",
    "postal": "",
    "middle_name": "",
    "zip": "",
    "rand_id": 525433267,
    "subscriptionhistory": [],
    "source": "",
    "state": "",
    "location": "/rest/v1/location/1026/",
    "subscription_status": "never",
    "email": "happynewuser@example.com",
    "subscriptions": [],
    "address1": "",
    "address2": "",
    "orderrecurrings": [],
    "eventsignups": [],
    "region": "",
    "password": "",
    "lang": null,
    "plus4": "",
    "fields": {},
    "created_at": "2012-03-19T14:20:50",
    "messages": [],
    "events": [],
    "token": ".1026.sHjDhr",
    "sent_mails": [],
    "country": "United States",
    "original": null,
    "resource_uri": "/rest/v1/user/1026/"
}

ActionKit decides how to deserialize input based on the Content-type header. In this example, we used JSON, by setting the header to application/json. Most HTTP clients will send POSTs with a Content-type of application/x-www-form-urlencoded by default. ActionKit decides what format to use to serialize the response by looking at the Accept header, but defaults to JSON.

To update our new user, we send a PUT request to the resource_uri of the new user. In this example, we'll update our new user's name and zip code.

$ curl -X PUT -i -u user:password -H 'Content-type: application/json' https://docs.actionkit.com/rest/v1/user/1026/ -d '{ "last_name": "User", "first_name": "Happy", "middle_name": "New", "zip": "10014" }'
HTTP/1.1 204 NO CONTENT
Date: Mon, 19 Mar 2012 14:50:16 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Length: 0
Content-Type: text/html; charset=utf-8

POST, PATCH, and PUT Response Status Codes:

Response Status Code Description
200 OK The request was successful, we updated the resource and the response body contains a representation.
201 CREATED The request was successful, we created a new resource and Location header contains the URI of the new resource.
202 ACCEPTED The request was successful, we updated the resource. (PATCH only)
204 NO CONTENT The request was successful, we updated the resource. (PUT only)
400 BAD REQUEST The data given in the POST, PATCH, or PUT failed validation. Inspect the response body for details.
401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to create or update the resource.
404 NOT FOUND Resource not found.
405 METHOD NOT ALLOWED You can't POST, PATCH, or PUT to the resource.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 SERVER ERROR We couldn't create or update the resource. Please try again.

Deleting Resources with DELETE

To delete a resource make an HTTP DELETE request to the resource's URL.

Note

Not all ActionKit REST API resources support DELETE. Some of them are hideable by updating a hidden field to 1. You can look at the schema to know if you can use the DELETE method, it will be listed under allowed_detail_http_methods.

For example, the schema for Phones says we can delete phones:

$ curl -u user:password https://docs.actionkit.com/rest/v1/phone/schema/
{
    "default_format": "application/json",
    "default_limit": 20,
    "allowed_list_http_methods": [
        "get",
        "post"
    ],
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "fields": {
        ... snip ...
    }
}

Example:

$ curl -X DELETE -i -u user:password https://docs.actionkit.com/rest/v1/phone/1/
HTTP/1.1 204 NO CONTENT
Date: Mon, 19 Mar 2012 16:41:38 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Length: 0
Content-Type: text/html; charset=utf-8

DELETE Response Status Codes:

Response Status Code Description
204 OK The request was successful; the resource was deleted.
401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to delete the resource.
404 NOT FOUND Resource not found.
405 METHOD NOT ALLOWED You can't DELETE the resource.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 SERVER ERROR We couldn't delete the resource. Please try again.

GET'ing a resource

Requesting the collection of allowed page fields:

$ curl -X GET -i -u user:password https://docs.actionkit.com/rest/v1/allowedpagefield/
HTTP/1.1 200 OK
Date: Mon, 19 Mar 2012 17:36:26 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "meta": {
        "previous": null,
        "total_count": 3,
        "offset": 0,
        "limit": 20,
        "next": null
    },
    "objects": [
        {
            "name": "favorite_city",
            "created_at": "2012-03-19T17:36:23",
            "updated_at": "2012-03-19T17:36:23",
            "always_show": false,
            "hidden": false,
            "resource_uri": "/rest/v1/allowedpagefield/favorite_city/"
        },
        {
            "name": "favorite_color",
            "created_at": "2012-03-19T17:36:14",
            "updated_at": "2012-03-19T17:36:14",
            "always_show": false,
            "hidden": false,
            "resource_uri": "/rest/v1/allowedpagefield/favorite_color/"
        },
        {
            "name": "favorite_food",
            "created_at": "2012-03-19T17:36:19",
            "updated_at": "2012-03-19T17:36:19",
            "always_show": false,
            "hidden": false,
            "resource_uri": "/rest/v1/allowedpagefield/favorite_food/"
        }
    ]
}

Requesting a single allowed page field:

$ curl -i -u user:password https://docs.actionkit.com/rest/v1/allowedpagefield/favorite_food/
HTTP/1.1 200 OK
Date: Mon, 19 Mar 2012 17:39:42 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "name": "favorite_food",
    "created_at": "2012-03-19T17:36:19",
    "updated_at": "2012-03-19T17:36:19",
    "always_show": false,
    "hidden": false,
    "resource_uri": "/rest/v1/allowedpagefield/favorite_food/"
}

POST'ing AND PUT'ing

To add a new allowed user field POST to the collection resource for the type. Here's how we add a new allowed page field:

$ curl -X POST -H 'Content-type: application/json' -i -u user:password https://docs.actionkit.com/rest/v1/allowedpagefield/ -d '{ "name": "favorite_food" }'
HTTP/1.1 201 CREATED
Date: Mon, 19 Mar 2012 17:36:19 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: text/html; charset=utf-8
Location: https://docs.actionkit.com/rest/v1/allowedpagefield/favorite_food/
Content-Length: 0

The URI for the new resource is returned in the Location header. To update an existing resource, make a PUT request to the resource's URI. For example:

$ curl -u user:password -i -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json; charset=utf-8' https://docs.actionkit.com/rest/v1/allowedpagefield/favorite_food/ -d '{ "name": "favorite_cuisine" }'
HTTP/1.1 204 NO CONTENT
Date: Thu, 22 Dec 2011 16:33:58 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Length: 0
Content-Type: text/html; charset=utf-8

DELETE'ing

You can delete resources by sending a DELETE request to the resource's URI. For example,

$ curl -u user:password -i -X DELETE https://docs.actionkit.com/rest/v1/allowedpagefield/favorite_cuisine/
HTTP/1.1 204 NO CONTENT
Date: Mon, 19 Mar 2012 17:55:58 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Length: 0
Content-Type: text/html; charset=utf-8

Delete really and truly deletes. Trying to load the resource we just deleted returns a 404 - because it's gone. Forever.

$ curl -u user:password -i -X GET https://docs.actionkit.com/rest/v1/allowedpagefield/favorite_cuisine/
HTTP/1.1 404 NOT FOUND
Date: Mon, 19 Mar 2012 18:14:00 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: text/html; charset=utf-8

Exceptions

ActionKit will return the status code in the HTTP Response header and a message in the body of the response. The details of the response may vary with the resource.

Here's an example of POST that is missing a required field:

$ curl -X POST -H 'Content-type: application/json' -i -u user:password https://docs.actionkit.com/rest/v1/allowedpagefield/ -d '{}'
HTTP/1.1 400 BAD REQUEST
Date: Mon, 19 Mar 2012 18:16:35 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Connection: close
Transfer-Encoding: chunked

{"name": ["This field is required."]}