The document discusses best practices for crafting evolvable API responses. It advocates taking back control of representations by thinking of responses as messages rather than objects. This allows APIs to build payloads with just enough data to solve the problem and survive changes over time. The document explores using attribute groups, links, and established formats like HAL and JSON-LD to build representations that are minimal yet provide essential context.

1. Crafting Evolvable API
Responses

2. Who am I?
• Twitter: @darrel_miller
• http://www.bizcoder.com/

3. Journey
• Versioning sucks, let’s just not do it
• Why we think we need it?
• How can we avoid it?
• Example time

4. Objects over the wire

5. We have been here before
• CORBA, DCOM
• SOAP, WSDL
• DTOs
• JSON

6. The ASP.NET Web API Project Template
public class ValuesController : ApiController
{
// GET api/values
public IEnumerable<string> Get() { return new string[] { "value1", "value2" };}
// GET api/values/5
public string Get(int id) { return "value"; }
// POST api/values
public void Post([FromBody]string value) { }
// PUT api/values/5
public void Put(int id, [FromBody]string value) { }
// DELETE api/values/5
public void Delete(int id) { }
}

7. The ASP.NET Web API Starter Tutorial
public class ProductsController : ApiController
{
//…
public IEnumerable<Product> GetAllProducts()
{
return products;
}
public IHttpActionResult GetProduct(int id)
{
var product = products.FirstOrDefault((p) => p.Id == id);
if (product == null)
{
return NotFound();
}
return Ok(product);
}
}
http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/tutorial-your-first-web-api

8. ServiceStack
public class ReqstarsService : Service
{
public List<Reqstar> Get(AllReqstars request)
{
return Db.Select<Reqstar>();
}
}

9. NancyFX
public class SampleModule : Nancy.NancyModule
{
public SampleModule()
{
Get["/"] = _ => "Hello World!";
}
}

10. Python Flask
@app.route('/todo/api/v1.0/tasks', methods=['GET'])
def get_tasks():
return jsonify({'tasks': tasks})

11. Rails
# Returns the resource from the created instance variable
# @return [Object]
def get_resource
instance_variable_get("@#{resource_name}")
end

12. But, what’s the problem?

13. Which objects to map?
• Domain objects
• How do we hide content we don’t want to expose?
• How do we create different views of data?
• Changes to domain model cause changes to API
• DTOs
• whole lot of busy work
• Only indirect control over serialization process

14. Automatic Serialization
• All the properties
• Non standard data types: datetime, timespan
• Does null mean unspecified, or explicitly null?
• Empty collection or no collection
• Capitalization
• Links
• Loops
• Changes to behavior in the frameworks

15. Take back control

16. Use a DOM to build your document
dynamic jspeaker = new JObject();
jspeaker.name = speakerInfo.Name;
jspeaker.bio = speakerInfo.Bio;
dynamic links = new JObject();
dynamic iconLink = new JObject();
iconLink.href = speakerInfo.ImageUrl;
links.icon = iconLink;
dynamic sessionsLink = new JObject();
sessionsLink.href = SessionsLinkHelper.CreateLink(request, speakerInfo).Target;
links[LinkHelper.GetLinkRelationTypeName<SessionsLink>()] = sessionsLink;
jspeaker["_links"] = links;
return new DynamicHalContent(jspeaker);

17. What to do with your new found freedom?

18. Anatomy of an HTTP representation
• Status line
• Headers
• Body

19. Headers
• Performance
• Timing
• Naming
• Content
• Compression

20. Let’s build some payloads

21. The smallest thing that is actionable
{
"description" :"There is a hole in my bucket"
}

22. Define a vocabulary for things of interest
{
"issue" : {
"description" :"There is a hole in my bucket"
}
}
application/json application/vnd.myapirespones+json application/vnd.issue+json

23. Beware of structural changes
{
"issues" : [
{
"description" :"There is a hole in my bucket"
}
]
}

24. Just enough data to solve the problem
{
"description" :"There is a hole in my bucket",
"stepsToReproduce" : "Pour water in bucket. Lift bucket off ground.
Look for water dripping",
"dateReported": "2012-04-21T18:25:43-05:00"
}

25. Why do they need that data?
{
"description" :"The font is too big",
"applicationName" : "Wordament",
"applicationVersion" : "1.2.0.2392",
"environment_OSVersion" : "NT4.0",
"environment_MemoryFree" : "10MB",
"environment_DiskSpaceFree" : "100TB",
}

26. Attribute Groups
{
"description" :"The font is too big",
"applicationName" : "Wordament",
"applicationVersion" : "1.2.0.2392",
"environment" : { "osVersion" : "NT4.0",
"memoryFree" : "10MB",
"diskSpaceFree" : "100TB"
}
}

27. Attribute Groups for multiple instances
{
"description" :"The font is too big",
"history" : [
{"status" : "reported", "date" :"2014-02-01"},
{"status" : "triaged", "date" :"2014-02-04"},
{"status" : "assigned", "date" :"2014-02-12"},
{"status" : "resolved", "date" :"2014-02-19"},
]
}

28. {
"description" :"The font is too big",
"reportedByUser" : { "name" : "Bob Bing",
"email" : "bob@acme.com",
"twitter" : "@bobbing",
"dateHired" : "2001-01-21"
}
}
Attribute Groups for related data

29. {
"description" :"The font is too big",
"reportedByUser_url" : "http://api.acme.com/users/75"
}
Linking related data

30. {
"description" :"The font is too big",
"Links" : [
{ "href" :"http://api.acme.com/users/75", "rel": "reportedByUser" },
{ "href" :"http://api.acme.com/users/24", "rel": "assignedToUser" }
]
}
Multiple Links

31. Learn from others
application/hal+json
application/vnd.collection+json
application/vnd.siren+json
application/vnd.github.v3+json
application/json-home
application/json-ld
application/vnd.heroku+json
application/http-problem
application/activity+json
application/vnd.mason+json

32. {
"description" :"The font is too big",
"_embedded" : {
"reportedByUser" : {
"name" : "Bob Bing",
"email" : "bob@acme.com",
"_links" : { "self" : {"href" :"http://api.acme.com/users/75"}}
}
}
Meet application/hal+json

33. Meet application/vnd.collection+json
{
"collection": { "links": [],
"items": [
{
"data": [
{ "name": "Title",
"value": "rntttLearning from Noda Time: a case study in API design and open source (good, bad and ugly)rntt“ },
{ "name": "Timeslot",
"value": "04 December 2013 16:20 - 17:20“ },
{ "name": "Speaker",
"value": "Jon Skeet“ }
],
"links": [ {
"href": "http://conference.hypermediaapi.com/speaker/6",
"rel": "http://tavis.net/rels/speaker" }, {
"href": "http://conference.hypermediaapi.com/session/133/topics",
"rel": "http://tavis.net/rels/topics" }
],
"href": "http://conference.hypermediaapi.com/session/133"
}
],
"query": [], "template": { "data": [] },
"version": "1.0"
}
}

34. Wrap up
• Understand the limitations of “objects over the wire”
• Consider taking back control of your representations
• Think in terms of messages, instead of objects
• Build software that is designed to survive change

36. Image Credits
• Package - https://flic.kr/p/3mrNyn
• Freedom - https://flic.kr/p/4vwRDw
• Treasure map - https://flic.kr/p/7jDJwi
• Handshake - https://flic.kr/p/nbAu8Y
• Telephone - https://flic.kr/p/7Q8bMd
• Blindfolded Typing - https://flic.kr/p/53Q3JE
• Magic Trick - https://flic.kr/p/7T8zk5
• Donut machine - https://flic.kr/p/anncxf
• GT-R Steering Wheel - https://flic.kr/p/fDUSDk
• Anatomy - https://flic.kr/p/6bfUZn
• Shapes - https://flic.kr/p/3aKUAq
• Payloaders - https://flic.kr/p/dTU9sN
• Birds on a Wire - https://flic.kr/p/4YdfK