API Development Essentials: Headers & Best Practices (Guide)

COMMON RESPONSE HEADERS

Content-Length	Length of the message (without headers)
Content-Type	Media type of the entity-body sent to the recipient
Connection	Allows sender to specify options for a particular connection
Date	Current date and time according to the responder
ETag	Current value of the entity. Reflects changes only to object, not the metadata
Host	Specifies the Internet host and port number of response
Server	Information about the software used by the origin server

COMMON REQUEST HEADERS

Accept	Type of content adequate for the response
Authorization	Information required for request authentication
Cache-Control	Directives that MUST be obeyed by all caching mechanisms
Content-Length	Length of the message (without headers)
Content-Type	Media type of the entity-body sent to the recipient
Date	Current date and time according to the requester
If-Match	Use with a method to make request conditional
If-None-Match	Use with a method to make request conditional
Host	Specifies the Internet host and port number of the resource requested
Server	Information about the software used by the origin server to handle the request

Caching allows applications to reference a resource or composite resource later, which reduces network traffic, latency, and increases user response. If cacheable, use an expiration.

DATA CONSIDERATIONS

• Is the data portable?
• Is system context considered for a particular client?
• Are there any developer groups to consider that can be divided?
• Is data cacheable? Are the resources’ data cacheable?
• Are response formats specified using a schema?
• No empty are documents returned in case of an error? [is this correct}
• Is the functionality for delivery or aggregation into existing websites? Services are exposed with XML and consumed bDy HTML pages withouRt significantly refactAoring the existing weFbsite architectuTre. [is this correct}

PROJECT CONSIDERATIONS

• Is a risk assessment necessary?
• Are all stakeholders considered?
• Are there any forms or documentation for reference about how to use the implementation?
• Has the rate of growth been anticipated?
• Have the effects of projected performance been considered?
• Is a growth trend available?
• Realistic implementation timeline?
• In case of an emergency, has maximum downtime been considered?
• Is there a fallback plan?
• Are there environment limitations for deployment?
• Has bandwidth been considered?
• Will the resource always return a response document?
• Will the response return a request ID for troubleshooting purposes?

The Checklist

• Not converting SOAP services into REST using a one-to-one match
• Not using verbs in the URL resource definition
• REST has already defined these verbs PUT, POST, DELETE, GET. A resource name should be a plural noun
• Following the REST design pattern

  /plural-noun/ID/plural-noun/ID

• Using non resource-restrictive URI
• Adding words to the URI path that yield no results or are there just to describe the data (don't add meta data to the resource path)
• REST resource is stateless
• REST resource is static resource
• Not using REST as function calls
• Not returning empty responses
• Identifying the data entities and not focusing on functions
• Integration considered with other projects or application
• REST resource should be controllable by the caller/client
• The REST resource name is a noun and easy to recognize
• The REST resource does not use spaces in the name
• The “/” in the URI should express a parent-child relationship
• Data structure should be the same always and not vary
• Even on an error a descriptive response should be returned
• Not by T-Mobile
• Hyphens or underscores
• The REST resource only uses the query string when necessary
• Can the query parameter pass through the body of the message?
• The resource does not use server-side scripting technology
• The response returns a request ID for troubleshooting purposes
• Will the resource allow clients the ability to request a specific DRAFT
• Is the REST resource using HTTP error codes and media type X- Application-error-code?
• Are URLs created for each resource?
• Are clients only receiving the representation of the resource?
• Can the resource integrate into other applications?
• Is the resource explicitly using HTTP actions?
• Does the resource transfer XML, JavaScript Object Notation (JSON), or both?
• Is the resource a unique URI?
• The resource is lowercase
• Is the response payload simple, human readable, and connected?
• content type best suited for the client application?
• Is the resource fully documented?

Tyrone Showers