API_Style_Guide

API Style Guide

General Guidelines

Follow the REST pattern. Design the API using nouns, not verbs. Our verbs are HTTP methods.

• Bad: -GET /api/provider_accounts/1/check_connection-
• Good: GET /api/provider_accounts/1/connection_status

Basic Resource Lifecycle

TODO: rest of the actions here

CREATE

• Return 201 Created if the creation of the resource was completed before responding. The response body should contain representation of the resource just created (like for GET request).
• Return 202 Accepted if the creation of the resource will happen after responding. Indicate location where client can query for status of the resource being created

UPDATE

• Return 200 OK if the update of the resource was completed before responding. Return the updated resource in the body
• Return 202 Accepted if the update of the resource was queued. Point client to the URL on which the client can pool for the update status. This URL could be the URL of the resource if the resource have ‘state’ attribute.

DELETE

• Return 204 No Content on a successful delete. The body of the response should be empty.

Referencing Other Resources

For referencing we use a “minimal resources” concept -- an XML element that has href and id attributes and has no child elements.

<pool_family href='http://host.domain/api/pool_families/2' id='2'></pool_family>

This format should be also accepted as input for POST and PUT requests when creating/updating a resource.

• Bad: -<catalog><pool_id>2</pool_id></catalog>-
• Good: <catalog><pool id='2'/></catalog>

Responding to Errors

• HTTP status codes

  • 400 Bad Request for bad requests :) (incorrect data, validation failed etc.)
  • 401 Unauthorized when authentication is required
    • 403 Forbidden when authentication credentials are incorrect
  • 404 Not Found when requesting non-existent resources and resource collections (also attempting to update/delete non-existent resources etc.)
  • 500 Internal Server Error when something unexpected happens

• Body of the response should look similar to the code example below.

  • Code is used to specify the kind of the error in a machine-readable way.
  • Message is a human-readable description of the error. <error> <code>RecordNotFound</code> <message>Couldn't find Pool with id=3</message> </error>

• Validation errors should return error code ValidationError and the message should contain text description of all the errors.