When working with API clients there are several distinct areas of concern. Each of these happen in sequence and are used with the goal of receiving a Domain Model at the end.

• Configuration
• Connection Handling
• Request Building
• Request Handling
• Response Handling
• Domain Modeling

The configuration object sets up the different variables you will use throughout your interactions. It can be used to:

• Set Defaults
• Allow User Provided values

This answers the question: can we communicate with the server?

This involves things like:

• Establishing a connection (is the server responding at all?)
• Specifying a timeout for retries
• Ensuring the response code is not in the 500 range

This phase allows you to prepare your request that you want to make. This includes things like:

• HTTP Headers
• HTTP Query String Params
• HTTP Body Params

This phase should provide a DSL to build requests in a consistent manner. The specific client could then have very specific implementations of the details (IE: Using Query String params like Google API)

This answers the question: Can you provide me the resource with this representation?

This takes the Request Builder from the last phase, combines in with the Connection Handling, and issues a request to the server.

One a request has been issued, there is a response that includes things like:

• HTTP Response body (according to content negotiation - CSV, JSON, etc)
• HTTP Status Code
• HTTP Headers
• Full Raw Response

The response Header itself carries some important client information as well, such as:

• Scope listing
• Content Negotiation
• Allow information
• Caching information
• OAuth Information
• Link information

The goal here is to ensure we get a 200 range response. Not all responses will include a body. We also need to figure out if we want to follow redirects and for how many hops (avoid infinite redirect loops).

We've configured, connected, build our request, issued the request to the server, and received a response. Now it's time to take that response and turn it into the Core Domain Model.

In most cases this is translating the JSON response into meaningful objects. The body itself may include other pieces of helpful information:

• Metadata
• Paginatation Information
• Links
• Data/Results - the body itself

Each of these models will translate accordingly and can be used to then issue subsequent requests.

• PAW: Mac Client, allows you to build requests and see responses.
  • Build the request itself with headers and params
  • View the request as a URL and as cURL and other tools.
  • View the response as raw output, or separated by headers and body
  • Allows you to extract environment variables for use in requests (configuration)