to do spec

Hypermedia API "bake off -- ToDo API Specification"

ToDo API "spec"

Below is a series of simple Actions and Fields along with MUST, MAY, and SHOULD references. These references are based on RFC2119 which outlines and meaning and use of these words.

For those interested, there is also an ALPS document that describes this specification.

ACTIONS

Users MUST be able to:

• create a new to-do item
• get a list of to-do items
• get a single to-do item
• mark a to-do item complete (or incomplete)

Users SHOULD be able to:

• edit a to-do item
• assign/change the due-date of a to-do item

Users MAY be able to:

• delete a to-do item

• send a to-do item to another user

• get a list of category items

• get a single category item

• create a category item

• edit a category item

• assign/change the category of a to-do item

• delete a category item

• create a user account

• log in as an authenticated user

• edit the user account

• delete the user account

FIELDS

to-do items MUST have the following fields

• id (globally unique)
• title (name of the thing to do)

They SHOULD have:

• due-date

They MAY have:

• notes (additional text about the item)
• category (this MAY hold more then one category value)
• useraccount (owner of the item)
• dateCreated
• dateUpdated

category items MUST have:

• id (globally unique)
• title (name of the category)

category items MAY have:

• dateCreated
• dateUpdated
• useraccount (user who created the item)

user items MUST have:

• id (globally unique)
• userName
• password

user items SHOULD have:

• givenName
• familyName

user items MAY have:

• avatarUrl
• dateCreated
• dateUpdated
• userUrl (address of server that accepts "sent to-do items" for this user)

Example Todo API