API Evolution Kata

Today's Kata will evolve a simple API from both the server and the client point of view. The end goal is to produce an API for crafting delicious, delicious burritos.

You will need a pair for this. One person will be writing the server and one person will be writing the client. This will let us evolve our API quickly and require both people to make the appropriate changes. Luckily, Hyper can play both roles!

1. Ping Pong

To start off, let's get our client and server talking to each other. We need to create a /ping endpoint that responds with a simple text response of "PONG". Don't overthink this one, it's our Hello World for Hyper. This gets the project setup, code compiling, and the network issues worked out.

2. Versioning

Naturally, we want to provide our clients stability when using our service. One good step towards that is going to be implementing API versioning. This will let old clients continue to talk to our server without preventing us from making changes.

It's your call on how you implement versioning. Classic schemes include HTTP headers, url params, or route segments. This is a good thing to build in now so we can gradually evolve our API over the next few steps.

Convert our versionless /ping endpoint to be v1
Add a new /burrito endpoint that sends back a simple text response of "BURRITOS ARE GO"

Going forward, on the server side, you'll want to keep the handlers around for the older versions of the API. If you only have a single handler you won't be able to make new API versions. On the client side, you'll want to keep your old clients around too. These can test the server's compliance and support for old versions.

3. Superfluous Version Bump!

Now that we can version things, let's change things up!

Add a timestamp to the response of /ping
Change the response of /burrito to be "THIS IS A BURRITO"

Both of these endpoints have now changed, but the v1 endpoints should still return the same old values. This means that the old client from a few minutes ago still works! Graceful updates for the win!

4. Structured Message Format

Sending back simple text response in an HTTP body works, but it's a far cry from a useful, working burrito api. Let's give the messages some structure. You can use simple newline delimiters, json, xml, yaml -- anything you want. You need to agree on the format between the client and the server though.

Convert /ping and /burrito to use your agreed upon message format
Separate /ping's "PONG" response from the timestamp so they can be used easily parsed by the client
Add a created_at field to the /burrito response

5. Metadata

We want to be able to add some extra metadata to our responses. Let's break apart metadata from the core response.

Add a separate section for metadata to each response.
Add a metadata field for volley_count to the /ping endpoint that tracks how many times it has been pinged.
Add a metadata field for allergy_warnings to the /burrito endpoint

6. Require Input

We can't just guess about what you want in your burrito! Turn the /burrito endpoint into a POST call that collects a bunch of parameters required for making a burrito.

N. New Optional Field

We don't always want to break client compatability when we change something. We can state that new fields can be ignored by clients that aren't aware of them.

Let clients add a param, hd, for getting back a high definition burrito.
Add an hd field to the /burrito endpoint that returns a the high def burrito.

              (    (    (               )   
   (          )\ ) )\ ) )\ )  *   )  ( /(   
 ( )\     (  (()/((()/((()/(` )  /(  )\())  
 )((_)    )\  /(_))/(_))/(_))( )(_))((_)\   
((_)_  _ ((_)(_)) (_)) (_)) (_(_())   ((_)  
 | _ )| | | || _ \| _ \|_ _||_   _|  / _ \  
 | _ \| |_| ||   /|   / | |   | |   | (_) | 
 |___/ \___/ |_|_\|_|_\|___|  |_|    \___/

N. Errors

We won't always provide a client with great errors, but we can probably do better than we have been. Let's specify some error handling expectations for our clients.

N. Deprecation Warnings

When an older client continues to use an endpoint we should give them a gentle warning.

Add a deprecation section for the v5 api endpoints, advising that older clients upgrade. This should be a non-breaking change!

saterus/api_evolution_kata.md