URL Resource Design

[Jeffrey Haynes]

We are trying to design our API using the following URL template: 

/{version}/{namespace}/{resource}/{resource-id}/{sub-resource}/{sub-resource-id}

Is it OK that a resource in namespace "A" references a resource in namespace "B"? If the version for namespace "A" differs from the version for namespace "B", there could be confusion about what version of resources in namespace "B" are required for resources in namespace "A". We are using HATEOAS and will be returning links to all the resources, including those in namespace "B".  So it seems like this might be OK.

Each namespace in our system represents a functional set of related resources.

What is the thinking on this here in API Craft?

Thanks

Jeff

[Kijana Woodard]

Namespaces don't exist...like spoons. ;-p

Especially with hypermedia, you could just as well replace the above with

/{uuid}

The clients would function the same.

All that do say, if different versions and namespaces will work for a given client, have fun.

IMO, you should drop version. That's controversial, but for me it's making a bad promise to both clients and to the business. Rather than version at the top level, each resource should version independently. If there *must* be a breaking change, we're very specific about what is broken. If it really is changing the entire api to something incompatible, you may as well change from "api.example.com" to "mauve-api.example.com".

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Jay C]

Slide 57 along with the accompanying YouTube video from this presentation (http://www.slideshare.net/apigee/restful-api-design-second-edition) says to push the version url as far to the left in the url path that you can.  So I think it is correct to start with /{version}/

[Darrel Miller]

 

I believe most practitioners who have supported multiple APIs over a multiple year lifespan will disagree with that guidance for all but a few scenarios where it is easy to synchronize client and server deployment.

 

If has been popular guidance for a while now, and it is commonly deployed.  However, if you really care about your customers and the longevity of your API, I believe it is time to stop.

 

Darrel

--

[Jay C]

@Darrel, so if using a version number in the url (left most is preferred) is wrong then what is the right solution?

[Darrel Miller]

Jay,

 

From: api-...@googlegroups.com [mailto:api-...@googlegroups.com] On Behalf Of Jay C

@Darrel, so if using a version number in the url (left most is preferred) is wrong then what is the right solution?

 

The right solution to what problem?

 

I really this sounds like I’m being difficult, but the reality is there is no simple answer to the challenge of managing change.  Versioning at the left of a URL is a sledgehammer approach to versioning.  Dealing with change at resource, link relation and media type level is a much more gentle approach.

 

As a more concrete example, if you have a /api/customer/{id} class of resource and you _really_ need to make a breaking change, then creating a /api/customer/v2/{id} resource that will sit alongside the original is a more friendly way of introducing the change.

 

Having said this, I believe that many cases where breaking changes to an API are needed  could have been avoided with some up front planning and some guidance to customers on how to build client code that would be resilient to potential future changes.

 

There are a couple of talks that I do that dig deeper into this subject

 

Crafting Evolvable Web API Representations

https://vimeo.com/131643022

 

Consuming REST APIs

http://tv.ssw.com/6391/consuming-rest-apis-for-all-interpretations-of-rest-darrel-miller-at-ddd-melbourne-2015

 

and I talk about many of the same things in the chapter I wrote in “Designing Evolvable Web APIs” which you can read online for free here http://chimera.labs.oreilly.com/books/1234000001708

 

 

Darrel

 

[Kijana Woodard]

If you break it down, versioning "to the left" makes no sense.

Your api has 50 resources. I'm happily using /api.example.com/v1/a. You make a breaking change to resource /api.example.com/v1/z and therefore bump the api to v2. Now I'm forced to update, test, and redeploy my code because /api.example.com/v1/a has been *replaced* by /api.example.com/v2/a. There's no assumption I can make there because this a totally new resource. I *must* retest.

Why? 

Version each resource independently and then I only need to take action when something I care about has a breaking change [which should be rare].

Apigee has that guidance because versioning is part of their "feature set" [1]. This is what all vendors sell: "you won't have to think about things, just let us take care of the rough bits". That never means that's a good idea.

Obligatory appeal to authority:

https://twitter.com/fielding/status/376835835670167552

http://www.slideshare.net/evolve_conference/201308-fielding-evolve [slide 31]

[1] https://community.apigee.com/articles/2325/versioning-your-apis-in-apigee-best-practices-and-1.html

--

[Darrel Miller]

Kijana,

> From: api-...@googlegroups.com [mailto:api-...@googlegroups.com] On Behalf Of Kijana Woodard
>
> Apigee has that guidance because versioning is part of their "feature set" [1].

I know our viewpoint on this subject is pretty much the same, however, I don't think any vendor should hold any responsibility for this practice. Vendors support this style of versioning because customers have asked for it because "best practices" documents all over the web recommend it.

I believe the practice is just a carry-over from the world of building local systems. We have tried to apply the notion of a programmatic "interface" to network based system. In the local world an interface is considered an atomic thing. If you change any aspect of that interface then it requires giving that interface a new name or version. In local systems we have the advantage of having many "interfaces" in a single system and we can keep those interfaces very small and focused, so the impact of a change to an interface is minimized. Composing lots of small HTTP APIs into a single larger API is much more tricky. Versioning an entire HTTP API tends to put a huge constraint on how that API can change.

We have the advantage that an HTTP interaction is much more flexible and resilient to change than the procedural interaction that occurs in a local system. Assuming of course we build HTTP clients to take advantage of that flexibility. We don't need to apply the "versioned interface" paradigm to HTTP APIs because HTTP has so many alternative ways of dealing with change over time. The downside of course is that we need to have a good understanding of HTTP and it is difficult to produce tooling that can automatically deal with these changes.

The reality is that much of the tooling we are trying to use to make it easier to build APIs is actually forcing us to use the "versioned interface" approach and causing us more pain in the long run. We as developers need to start demanding tooling that won't just help up get a new API out of the door in three weeks, but tooling that will allow us to incrementally improve our API for years to come.

Historically I have blamed tooling vendors for causing many of the failures of distributed systems in the past, however, I am coming to realize that tooling vendors just build what customers are asking for.

Darrel

[Kijana Woodard]

"Historically I have blamed tooling vendors for causing many of the failures of distributed systems in the past, however, I am coming to realize that tooling vendors just build what customers are asking for."

Fair enough. It's a vicious circle that feeds itself. People ask for versioning because that's what they're used to.....so versioning is a "best practice" because all the vendors support it.

As with most things, thinking about what you really want and need is hard. It's easier to spend more time comparing vendor feature matrices. 

If getting something out quickly will "make or break" a project or company, then by all means, hack away.

I just don't like statements that purport "best practices" to go unchallenged.  :-D

Darrel

[Darrel Miller]

>From: api-...@googlegroups.com [mailto:api-...@googlegroups.com] On Behalf Of Kijana Woodard

>I just don't like statements that purport "best practices" to go unchallenged.  :-D

 

I’m 100% behind you on that.

 

[Eric Johnson]

We've settled on an approach that moves the version number one position to the right. That is, the "namespace" is what is being versioned, not that the versions are being "namespaced". And in our world, the namespace is optional, and whether it exists depends on number of responsibilities for the server.

However, you should, if at all possible, plan to never use the version number in the URL. It should only be used for breaking changes, and you should avoid that at all possible. If you have a JSON API, that should mostly be straightforward - add to your data results, never change the semantics of existing stuff. If you also provide an XML API, particularly with associated schemas, preserving API compatibility will be harder.

If you start putting a version number in the results you return, then you should be defining a media-type that your clients can read up on, so that they know what your version number inside the resource actually means.

Eric.