Strategies for Versioning Your RESTful API

Strategies for Versioning Your RESTful API

Web API versioning may not sound exciting, but do you really have a plan for version 2 of your API? If your answer is, "yeah, I'll just put 'v2' in the URI", then come listen to why that may not always be the best solution. In this session you'll learn what approaches are available for versioning your web API. We'll discuss what strategies may be the best and worse for each option. (Presented at Raleigh Code Camp 2014 http://codecamp.org/Raleigh).

3f668016faac65ce425e5b20c2b7265c?s=128

Justin Saraceno

November 08, 2014
Tweet

Transcript

  1. None
  2. API Versioning Strategies JUSTIN SARACENO RALEIGH CODE CAMP 2014

  3. Who Am I? Justin Saraceno justin.saraceno@gmail.com PeopleFluent http://peoplefluent.com Blog: http://www.justinsaraceno.com

    Twitter: @justinsaraceno GitHub: https://github.com/justinsaraceno Triangle .NET User Group - Co-Organizer
  4. The Plan RESTful API Design @ a 50,000’ View Strategies

    for API versioning. Pros & Cons of each option. What to consider when choosing a strategy?
  5. What is REST?

  6. RESTful vs REST-like VS

  7. “A RESTifarian is a zealous proponent of the REST software

    architectural style as defined by Roy T. Fielding in Chapter 5 of his PhD. dissertation at UCIrvine.” -Mike Schinkel Roy T. Fielding – Principal Scientist, Adobe
  8. RESTful Design Is A Big Topic! …and there are lots

    of opinions
  9. REST-like Sometimes referred to as pragmatic REST design Takes the

    principles of REST and adapts them to a given scenario For instance: HATEOAS (Hypermedia as the Engine of Application State)
  10. API design, including the versioning strategy, is more of an

    art than a science.
  11. But even a piece of art can be considered ‘bad

    design’. There are still guidelines!
  12. Who’s Right? RESTful APIs are implemented in many flavors The

    design of any API is a result of the developer’s interpretation of REST and the environment. No two APIs are alike Even high-profile APIs differ in their versioning strategy
  13. Why Version An API? API versioning IS NOT product versioning!

    An API is a contract APIs are versioned due to: Semantics Signatures Data Shape Changes V1 V2
  14. Finkle Einhorn

  15. Versioning With URI Example: http://www.[yoursite].com/api/v2/customers Most common versioning pattern. Allows

    you to drastically change the API. Used by these public APIs:
  16. URI Versioning Pros/Cons Pros: Simple to segregate old APIs for

    backwards compatibility. Easy to implement. Straight-forward for any consumer. Cons: Requires a lot of client changes when you version. Increases the size of the URI surface area you need to support.
  17. Versioning With Query String Example: http://www.[yoursite].com/api/customers?v=2 Version can be an

    optional query string parameter. The version can be defaulted if not provided. Used by:
  18. Query String Versioning Pro/Cons Pros: Without specifying version, the consumer

    can always get the latest version of the API. Minimal client changes are needed as the versions mature. Easy to consume. Cons: Setting a default version can surprise consumers with unintended changes. This can be mitigated by not making the version parameter optional.
  19. Versioning With Custom Header Example: x-myapi-version: 2014-11-08 The x- prefix

    is used because most routers will ignore it. …but this practice was officially deprecated by the Internet Engineering Task Force (IETF) in June 2012 Used by:
  20. Custom Header Versioning Pros & Cons Pros: Keeps API signature

    separate from the version number. Version numbers are tied to a specific resource version. Cons: Adding headers isn’t straight forward on all platforms. They are custom headers; real HTTP headers exist. Not all levels of developers will find working with headers easy in code.
  21. Versioning With Content Negotiation Example: Accept: application/vnd.ms-excel Uses custom Media

    types (Accept header) The standard custom Media type prefix is: vnd. Can include formatting in header - application/vnd.codecamp.customer-v2+json Used by:
  22. Content Negotiation Pros & Cons Pros: Clients only have to

    change Accept header to get the latest version. The resource and API are tied to the same version. RESTifarians will love you! (or they won’t?) Cons: Adding a custom content request isn’t easy on all platforms (JavaScript). The concept of custom headers isn’t easy to grasp for all levels of developers.
  23. Versioning With…… NOTHING [RESTifarians – please hold your applause] Think

    about this… api/customer/123 { "customer": { "id":1, "name": "Justin Saraceno" }} api/customerDetails/123 { "customer": { "id":1, "firstName": "Justin", "lastName": "Saraceno", "gender": "male" }}
  24. No Versioning Pros & Cons Pros: Resources become permalinks Resource

    names become specific and descriptive No need to deal with headers, changing URIs, or backwards compatibility Cons: The surface area of resources that need to be supported can grow rapidly if poorly managed Minor or frequent resource changes can be problematic Deprecating pieces of your API can be difficult to categorize and communicate
  25. The Path Forward… It’s important to have a versioning strategy

    so your consumers can rely on something stable while your product continues to evolve. API design (including versioning strategy) depends on many factors. Consider the audience of your developers and consumers. It’s okay to change/evolve your versioning scheme over time.
  26. Resources Pluralsight Courses: ◦ Web API Design ◦ Implementing an

    API in ASP.NET Web API ThereIsNoRightWay Blog Apress: ASP.NET Web API 2 Recipes StackOverflow Question: Best practices for API versioning
  27. Thank You! Visit JustinSaraceno.com for slides and demo code.