Question

I’m trying to create a REST web service that exposes the following Django model:

class Person(models.Model):
    uid = models.AutoField(primary_key=True)
    name = models.CharField(max_length=40)
    latitude = models.CharField(max_length=20)
    longitude = models.CharField(max_length=20)
    speed = models.CharField(max_length=10)
    date = models.DateTimeField(default=datetime.datetime.now)

    def __unicode__(self):
        return self.name

Here’s how I thought about it so far:

Get all Persons
URL: http://localhost/api/persons/
Method: GET
Querystring:

• startlat=
• endlat=
• startlng=
• endlng=

Used for getting the Persons that are within the specified coordinate range.

• page=

Used for getting the specified page of the response (if the response contains multiple pages).

Returns:

• 200 OK & JSON
• 404 Not Found

Example:
Request:

GET http://localhost/api/persons/?startlat=10&endlat=15&startlng=30&endlng=60

Response:

{
  "persons":
  [
     { "href": "1" },
     { "href": "2" },
     { "href": "3" },
     ...
     { "href": "100" }
  ],
  "next": "http://localhost/api/persons/?startlat=10&endlat=15&startlng=30&endlng=60&page=2"
}

Get info on a specified Person
URL: http://localhost/api/persons/[id]
Method: GET
Returns:

• 200 OK & JSON
• 404 Not Found

Example:
Request:

http://localhost/api/persons/5/

Response:

{
  "uid": "5",
  "name": "John Smith",
  "coordinates": {
                   "latitude":"14.43432",
                   "longitude":"56.4322"
                 },
  "speed": "12.6",
  "updated": "July 17, 2009, 8:46 a.m."
}

How correct is my attempt so far? Any suggestions are highly appreciated.

Answer 1

{ "href": "1" },

1 is hardly a valid URL. You should use full URLs. Google for HATEOAS.

Also, remember to send a relevant Content-Type header. You may want to make up your own mime-type to describe the format. This gives you the option to later change the content-type (Eg. change the format after publishing). See Versioning REST Web Services