API Tutorial

In this tutorial, you will learn how to query the API, create new objects in the database, edit existing objects, and delete objects. We will be issuing queries on the Event resource for simplicity, but all the methods below are applicable on all resources that have endpoints.

Note

See All Endpoints for a list of all API URIs.

Note

The methods described below are RESTful and comply with RFC2616.

Basic querying

We will start by querying the available events. Issue a GET request on the event resource URI (/marketplace/api/v1/mp_events/events/):

-> GET /marketplace/api/v1/mp_events/events/
.. Content-Type: application/json

<- 200 OK

The API should return a 200 status code and a list of objects:

Note

The following example truncates the list of objects to one. By default, the API shows 20 objects per page (See ::ref::pagination for more information on pagination).

{
    meta: {
        limit: 20,
        next: "/marketplace/api/v1/mp_events/events/?offset=20&limit=20&format=json",
        offset: 0,
        previous: null,
        total_count: 3208
    },
    objects: [
        {
            absolute_url: "/marketplace/businesses/sunflower-publishing/events/23/",
            business: "/marketplace/api/v1/business/business/8504/",
            created: "Wed, 2 May 2007 14:52:35 -0600",
            date: "1 Mar 2007",
            description: "A new publication representing a unique look into the lifestyles and interests of the Topeka KS area. Pick up your copy today!",
            end_time: null,
            id: "23",
            modified: "Wed, 2 May 2007 14:52:35 -0600",
            name: "Topeka Magazine",
            resource_uri: "/marketplace/api/v1/mp_events/events/23/",
            start_time: null
        } //, ...
    ]
}

The API list endpoints return a javascript object containing two attributes, meta and objects. The meta object contains some metadata about the request: The pagination information (limit, offset, and next and previous pages) as well as the total object count.

If we already know the resource URI of the object we want, we can issue a GET on that particular object. For example, the first object in the event list above has a business attribute with a value of /marketplace/businesses/sunflower-publishing/events/23/. This URI can be queried to get information about the business that is hosting the event:

-> GET /marketplace/api/v1/mp_events/events/23/
.. Content-Type: application/json

<- 200 OK
{
    "absolute_url": "/marketplace/businesses/sunflower-publishing/",
    "additional_hours_info": "",
    "address1": "609 New Hampshire",
    "address2": "",
    "business_type": {
        "codename": "service",
        "id": "4",
        "name": "Service"
    },
    "categories": [
        "/marketplace/api/v1/categories/categories/1715/",
        "/marketplace/api/v1/categories/categories/1771/"
    ],
    "city": "Lawrence",
    "created": "Wed, 12 May 2010 23:37:49 -0600",
    "description": "www.sunflowerpub.com\r\nSunflower Publishing is a print publishing company located in Lawrence KS. Our wide range of clients and projects creates a diverse project portfolio and allows us to excel at start to finish design, production, and sales. We are a small company uniquely positioned to provide big business resources while keeping us accessible to our customers.\r\n\r\nSunflower Publishing produces high-quality consumer magazines, books, and various programs and guides for Lawrence and the surrounding areas. We also provide start to finish production, including client consultation, advertising sales, printing, and distribution.",
    "email": "sunpubads@sunflower.com",
    "extension1": null,
    "extension2": null,
    "fax": "785-331-0633",
    "id": "8504",
    "latitude": 38.972549999999998,
    "longitude": -95.234880000000004,
    "mailing_address1": null,
    "mailing_address2": null,
    "mailing_city": null,
    "mailing_state": null,
    "mailing_zip_code": null,
    "meta_description": "",
    "modified": "Wed, 12 May 2010 23:37:58 -0600",
    "name": "Sunflower Publishing",
    "nickname": "",
    "phone1": "785-832-7257",
    "phone2": "",
    "photo": "http://127.0.0.1:8080/static/img/marketplace/businesses/images/2007/03/30/SunPub_MarketPlace_image_t400x300.jpg?985422e81f7b1e1c145b95018da19e56eb24dbf6",
    "point": "POINT (-95.2348800000000040 38.9725499999999982)",
    "pre_name": "",
    "resource_uri": "/marketplace/api/v1/business/business/8504/",
    "slug": "sunflower-publishing",
    "state": "KS",
    "suggested_type": "",
    "validated": true,
    "website": "http://www.sunflowerpub.com",
    "zip_code": "66044"
}

Creating new objects

To create new objects, POST a representation to the base resource URI:

Note

The Authorization header must be present with your correct credentials. See Authentication for more information.

-> POST /marketplace/api/v1/mp_events/events/
.. Content-Type: application/json
.. Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
{
    business: "/marketplace/api/v1/business/business/8504/",
    date: "1 Mar 2007",
    description: "A cool new event.",
    end_time: null,
    name: "My Cool Event",
    start_time: null
}

<- 201 CREATED
.. Location: http://yoursite.com/marketplace/api/v1/mp_events/events/3443/

Note that we are only supplying the fields that we need to create a new object. Some of the fields are read-only and do not need to be supplied when creating new objects. The server returns a response of status code 201 (CREATED), so we can query that URI to get information about the newly created object.

Note

To use the API from curl, open a terminal and run the following command (substituting the username/password and URL with your particular information):

curl -i -H "Content-Type: application/json" -X POST --basic -u 'username:password' \
    -d '{"business": "/marketplace/api/v1/business/business/8504/", "date": "1 Mar 2007", "description": "A new event.", "end_time": null, "name": "My Event", "start_time": null}' \
    http://mysite.com/marketplace/api/v1/mp_events/events/

Here are the flags used (see the curl man page for more information):

-i
Show response headers
-H "Content-Type: application/json"
Use Javascript Object Notation
-X POST
Issue a “POST” request (instead of “GET”)
--basic
Use HTTP basic authentication
-u "username:password"
Supply login credentials
-d '{...}'
Supply JSON data structure

After posting the new object, we can issue a GET request on the resulting resource URI:

-> GET /marketplace/api/v1/mp_events/events/3443/

<- 200 OK
{
    "absolute_url": "/marketplace/businesses/sunflower-publishing/events/3443/",
    "business": "/marketplace/api/v1/business/business/8504/",
    "created": "Fri, 3 Sep 2010 15:34:10 -0600",
    "date": "1 Mar 2007",
    "description": "A cool new event.",
    "end_time": null,
    "id": "3443",
    "modified": "Fri, 3 Sep 2010 15:34:10 -0600",
    "name": "My Cool Event",
    "resource_uri": "/marketplace/api/v1/mp_events/events/3443/",
    "start_time": null
}

Note that the created and modified times have been automatically provided.

Note

If using CURL to view JSON representations, pipe the result to python -m json.tool for pretty formatting:

curl http://mysite.com/marketplace/api/v1/mp_events/events/3443/ | python -m json.tool

Editing objects

Issue an HTTP PUT request against the resource URI to edit existing objects. On success, the server will respond with a 204 status code (no content):

-> PUT /marketplace/api/v1/mp_events/events/3443/
.. Content-Type: application/json
.. Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
{
    business: "/marketplace/api/v1/business/business/8504/",
    date: "1 Mar 2007",
    description: "A cool event with a new description.",
    end_time: null,
    name: "My Cool Event",
    start_time: null
}

<- 204 NO CONTENT

Deleting objects

Issue an HTTP DELETE request against the resource URI to delete and existing object. On sucess, the server will respond with a 204 status code (no content):

-> DELETE /marketplace/api/v1/mp_events/events/3443/

<- 204 NO CONTENT

Note

After deleting the object, it is completely removed and an attempt to retrieve it will result in a 410 GONE response.

Home

Browse

Glossary

You are here:

This Page