You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

This page is meant to start as a conceptual design for a 2nd generation REST API for ESME. The idea is to learn from the discussions around and use of the original REST API.

REST API Design

Methods, Resources, and Descriptions

Method

Resource

Description/Payload schema/Response schema

GET

api/sessions

(It might make sense for this to return only the current session, but in theory it would return all sessions that the current session is allowed to access, so for an administrator, it might return all open sessions. An individual session would be accessed at GET api/sessions/SESSIONID.)

POST

api/sessions?token=API_TOKEN

 

DELETE

api/sessions/SESSIONID

or
DELETE api/sessions?session=SESSIONID (get SESSIONID from api/sessions)

GET

api/users/USERID/messages

(get USERID from api/session)

GET

api/users/USERID/messages

(long-poll?)

GET

api/messages/MESSAGEID

Gets a particular message.

POST

api/messages?message=MESSAGE_BODY&via=CLIENT&tags=TAGS&metadata=XML&replyto=MESSAGEID

 

PUT

api/messages/MESSAGEID

(payload the same as POST)

DELETE

api/messages/MESSAGEID

 

GET

api/users/USERID/followees

 

GET

api/users/USERID/followers

 

POST

api/users/USERID/followees/USERID2

or POST api/users/USERID/followees?user=USERID2

DELETE

api/users/USERID/followees/USERID2

or DELETE api/users/USERID/followees?user=USERID2

GET

api/users

 

GET

api/tags

(This doesn't really seem like an appropriate API method. It should really return all of the tags, or user-specific tags (GET api/tags/USERID) and let the front-end decide what to do with it.)

GET

api/users/USERID/tracks

 

POST

api/users/USERID/tracks?track=TEXT_TO_TRACK

 

DELETE

api/users/USERID/tracks/TRACKID

 

GET

api/conversations/CONVERSATIONID

 

GET

api/users/USERID/actions

(Actions probably don't make sense outside of the context of a specific user.)

POST

api/users/USERID/actions?name=NAME&test=TEST&action=ACTION

 

PUT

api/users/USERID/actions/ACTIONID?enabled=true|false

(This is actually a general outlet to update any attribute of an action, including whether or not it is enabled.)

DELETE

api/users/USERID/actions/ACTIONID

 

One point to note is that most HTTP clients do not currently support the "PUT" or "DELETE" methods, so these have to be simulated through POST methods with an extra parameter. I think that because of the close mapping to resource verbs, is worth using these methods in the specification and defining the simulation method for the entire API separately.

Resource/Object Hierarchy

The above is based on a rough object hierarchy as follows:

  • ESME API instance (api/)
    • Sessions (api/sessions)
    • Users (api/users)
      • Messages posted by a user (api/users/USERID/messages)
      • Users followed by a user (api/users/USERID/followees)
      • Users following a user (api/users/USERID/followers)
      • Trackers belonging to a user (api/users/USERID/tracks)
      • Actions belonging to a user (api/users/USERID/actions)
    • Messages (api/messages)
    • Tags (api/tags)
    • Conversations (api/conversations)
    • Pools (api/pools)
      • ?

Each of these bullets represents a set of objects. The resource representing an individual object lives at api/objects/OBJECTID. For example, api/sessions/SESSIONID. As much as is reasonable, one would expect to be able to GET (read), POST (create), PUT (update/amend), or DELETE (delete) any individual member of each of these object sets. Going through each of these objects to ask what it would mean to create, read, update, or delete that object may reveal holes in the existing API, some of which I have filled in above.

Points for discussion, resolution, further work

  1. Is the use of HTTP sessions necessary? Is it desirable?
  2. Request signing methods?
  3. Payload and response schemas must be defined
  • No labels