4 ms·

The article gives some motivation for its best practices, you do not. Would you care to provide some? > using plurals is not the only, and probably not the sup

The article gives some motivation for its best practices, you do not. Would you care to provide some? > using plurals is not the only, and probably not the superior, solution. Why? > Whatever you do, putting "v1" in the middle of your URL is the wrong way to do it. Why? > Nesting resources is an anti-pattern that quickly creates a mess. Why? Edit: not sure why the downvotes. I'm genuinely interested, but the parent doesn't contain much useful content.

protonfish 12y ago
I suppose one must first define the qualities between a good and a poor API. I would say that it is the same as any code: The design should be readable, maintainable and modular. The plurals or not thing isn't a big deal. I really just object to the author picking one and claiming it's better with justification. Putting "vi" in your URL decreases both readability and modularity. All things being equal, concise URLs are more readable. "v1" are extra characters without significant benefit. It also creates huge maintenance overhead. How many APIs do you think you can simultaneously maintain well? I am happy with one good one myself. Every extra new version you create (as opposed to gracefully improving the existing one) is more technical debt. Let's take the nesting example: /artists/8/albums. What if you want to access an album by itself? You also need an /albums resource so you've just created two resources when you need only one. The /artists/8 response should include a list of albums that hyperlink to the /albums resources. If you absolutely have to have a clean list (without the artist header information, just filter it with a query string /albums/?artist=8. This accomplishes the same thing in a more predictable and consistent way without magic URL params. The major benefit of this type of design is it makes tracing execution from the interface to a code location much clearer by avoiding spaghetti URL routing.
- hesselink 12y ago
  Thanks for replying. > The plurals or not thing isn't a big deal. I really just object to the author picking one and claiming it's better with justification. Agreed, I was annoyed by that as well when reading the article. > Putting "vi" in your URL decreases both readability and modularity. All things being equal, concise URLs are more readable. "v1" are extra characters without significant benefit. It also creates huge maintenance overhead. How many APIs do you think you can simultaneously maintain well? I am happy with one good one myself. Every extra new version you create (as opposed to gracefully improving the existing one) is more technical debt. It is true that versioning your API creates more maintenance, since you're supporting old versions of your code. However, it does make things more maintainable for users of your API. If you don't provide at least two versions, there is really no way to make a breaking change to your API without breaking your API clients. We have an API that is now up to version (IIRC) v1.13.4, where the first two components indicate breaking changes, and the last component is for additions. While the extra maintenance is noticeable (and we sometimes discuss how to decrease it) it's not huge, and very manageable. And it's helped us maintain our own internal tools, as well as upgrade different services that talk to each other using these APIs, but can't be upgraded simultaneously. > Let's take the nesting example: /artists/8/albums. What if you want to access an album by itself? You also need an /albums resource so you've just created two resources when you need only one. The /artists/8 response should include a list of albums that hyperlink to the /albums resources. If you absolutely have to have a clean list (without the artist header information, just filter it with a query string /albums/?artist=8. This accomplishes the same thing in a more predictable and consistent way without magic URL params. The major benefit of this type of design is it makes tracing execution from the interface to a code location much clearer by avoiding spaghetti URL routing. I can see this if you have lots of domain objects that are related more loosely. However, for objects that are more closely related (say, a blog post and its comments) I can also see the advantages of the nested structure, and you'll probably never request a certain comment without first knowing the post. On the other hand, perhaps you want the comments but relating to a user instead of a post... How we've dealt with this is by mounting a sub-resource (comments, for example) on multiple parent resources (posts and users). This doesn't have to lead to complicated code if your abstractions are set up right. But I can definitely also see the advantages to a completely flat url structure. The more I think about it, the more I want to try this for a future API.
- jjbiotech 12y ago
  When developing an API that sits on top of HTTP, it's easy to use a web browser to develop/debug. The reason I include the version string in the URLs of my APIs is to enable browsers to consume the API without any added extensions for crafting HTTP headers. The same point could be used to argue in favor of HTTP basic auth.
- shangxiao 12y ago
  I've actually seen people use versioning in their URLs for deprecated APIs only, with the current version not using a version number.
  - Pxtl 12y ago
    That seems pointless, since you're still shifting the ground under your users' feet.
    - eli 12y ago
      What's the alternative?
      - jessaustin 12y ago
        Some say that if HATEOAS is followed, there should never be a reason for a client to "know" an API. The assumption is that every link in a resource can be characterized precisely (via link relations, profiles, media types, etc.) enough that automated clients know what they can do and how they should do it. In practice, we're not really to that point yet, but also in practice there is often a human around somewhere to help a client navigate a changed API even if it can't figure that out automatically.
        eli 12y ago
        I think I'd agree that automated clients have a ways to go before that works. But sometimes you don't even want anything automated: sometimes the API just needs to change because e.g. the world around it has changed, requirements have changed. A version string in the API seems like a reasonable way to do that.
        jessaustin 12y ago
        I think we can agree that there is some level of change at which we should not consider "the world" to have changed. I.e. if previously one could frobnobulate Widgets A, B, and C, and now Widget A has been replaced by Widgets Y and Z, that probably isn't a change to "the world". Only a client ill-conceived enough to maintain its own Widget Catalog would get screwed up by that change. (Don't laugh; this has been done lots of times.) Now suppose that before frobnobulating Widget B, we must first fizzgiggle it. There is a non-empty set of clients that survived the widget update but that will DIAF with the widget-specific-dependency-of-transitive-widget-verb update. So, don't write a Transitive-Widget-Verbs-and-Their-Widget-Specific-Dependencies Catalog into your client either. Et cetera... Eventually we'll all get to a point at which the generalization must stop. REST advocates think that point is much farther away than is commonly believed. In the case of my dumb example, giving the client developer a version number wouldn't really have helped her avoid a rewrite, because Widget A is no longer available and Widget B must be fizzgiggled before it is frobnobulated. You could imagine that she has enough pull to insist on treating her Widgets exactly as she pleases, but that's not the hypothesis here. (After all in that case she could just have her own entry URI.) It's much better to use media types, link relations, etc. to let the client implicitly learn the information it needs to know every time it needs to know it.
- cbau 12y ago
  Nested URLs are useful to signify partonomy. If you delete an artist, you would expect his or her albums to be deleted as well. Versus, if you delete an album, you wouldn't expect the artist to be deleted. And for completely unrelated things (which both would sit at the top level), again you wouldn't expect a cascading delete either.

protonfish 12y ago

I suppose one must first define the qualities between a good and a poor API. I would say that it is the same as any code: The design should be readable, maintainable and modular. The plurals or not thing isn't a big deal. I really just object to the author picking one and claiming it's better with justification. Putting "vi" in your URL decreases both readability and modularity. All things being equal, concise URLs are more readable. "v1" are extra characters without significant benefit. It also creates huge maintenance overhead. How many APIs do you think you can simultaneously maintain well? I am happy with one good one myself. Every extra new version you create (as opposed to gracefully improving the existing one) is more technical debt. Let's take the nesting example: /artists/8/albums. What if you want to access an album by itself? You also need an /albums resource so you've just created two resources when you need only one. The /artists/8 response should include a list of albums that hyperlink to the /albums resources. If you absolutely have to have a clean list (without the artist header information, just filter it with a query string /albums/?artist=8. This accomplishes the same thing in a more predictable and consistent way without magic URL params. The major benefit of this type of design is it makes tracing execution from the interface to a code location much clearer by avoiding spaghetti URL routing.

hesselink 12y ago
Thanks for replying. > The plurals or not thing isn't a big deal. I really just object to the author picking one and claiming it's better with justification. Agreed, I was annoyed by that as well when reading the article. > Putting "vi" in your URL decreases both readability and modularity. All things being equal, concise URLs are more readable. "v1" are extra characters without significant benefit. It also creates huge maintenance overhead. How many APIs do you think you can simultaneously maintain well? I am happy with one good one myself. Every extra new version you create (as opposed to gracefully improving the existing one) is more technical debt. It is true that versioning your API creates more maintenance, since you're supporting old versions of your code. However, it does make things more maintainable for users of your API. If you don't provide at least two versions, there is really no way to make a breaking change to your API without breaking your API clients. We have an API that is now up to version (IIRC) v1.13.4, where the first two components indicate breaking changes, and the last component is for additions. While the extra maintenance is noticeable (and we sometimes discuss how to decrease it) it's not huge, and very manageable. And it's helped us maintain our own internal tools, as well as upgrade different services that talk to each other using these APIs, but can't be upgraded simultaneously. > Let's take the nesting example: /artists/8/albums. What if you want to access an album by itself? You also need an /albums resource so you've just created two resources when you need only one. The /artists/8 response should include a list of albums that hyperlink to the /albums resources. If you absolutely have to have a clean list (without the artist header information, just filter it with a query string /albums/?artist=8. This accomplishes the same thing in a more predictable and consistent way without magic URL params. The major benefit of this type of design is it makes tracing execution from the interface to a code location much clearer by avoiding spaghetti URL routing. I can see this if you have lots of domain objects that are related more loosely. However, for objects that are more closely related (say, a blog post and its comments) I can also see the advantages of the nested structure, and you'll probably never request a certain comment without first knowing the post. On the other hand, perhaps you want the comments but relating to a user instead of a post... How we've dealt with this is by mounting a sub-resource (comments, for example) on multiple parent resources (posts and users). This doesn't have to lead to complicated code if your abstractions are set up right. But I can definitely also see the advantages to a completely flat url structure. The more I think about it, the more I want to try this for a future API.
jjbiotech 12y ago
When developing an API that sits on top of HTTP, it's easy to use a web browser to develop/debug. The reason I include the version string in the URLs of my APIs is to enable browsers to consume the API without any added extensions for crafting HTTP headers. The same point could be used to argue in favor of HTTP basic auth.
shangxiao 12y ago
I've actually seen people use versioning in their URLs for deprecated APIs only, with the current version not using a version number.
- Pxtl 12y ago
  That seems pointless, since you're still shifting the ground under your users' feet.
  - eli 12y ago
    What's the alternative?
    - jessaustin 12y ago
      Some say that if HATEOAS is followed, there should never be a reason for a client to "know" an API. The assumption is that every link in a resource can be characterized precisely (via link relations, profiles, media types, etc.) enough that automated clients know what they can do and how they should do it. In practice, we're not really to that point yet, but also in practice there is often a human around somewhere to help a client navigate a changed API even if it can't figure that out automatically.
      - eli 12y ago
        I think I'd agree that automated clients have a ways to go before that works. But sometimes you don't even want anything automated: sometimes the API just needs to change because e.g. the world around it has changed, requirements have changed. A version string in the API seems like a reasonable way to do that.
        jessaustin 12y ago
        I think we can agree that there is some level of change at which we should not consider "the world" to have changed. I.e. if previously one could frobnobulate Widgets A, B, and C, and now Widget A has been replaced by Widgets Y and Z, that probably isn't a change to "the world". Only a client ill-conceived enough to maintain its own Widget Catalog would get screwed up by that change. (Don't laugh; this has been done lots of times.) Now suppose that before frobnobulating Widget B, we must first fizzgiggle it. There is a non-empty set of clients that survived the widget update but that will DIAF with the widget-specific-dependency-of-transitive-widget-verb update. So, don't write a Transitive-Widget-Verbs-and-Their-Widget-Specific-Dependencies Catalog into your client either. Et cetera... Eventually we'll all get to a point at which the generalization must stop. REST advocates think that point is much farther away than is commonly believed. In the case of my dumb example, giving the client developer a version number wouldn't really have helped her avoid a rewrite, because Widget A is no longer available and Widget B must be fizzgiggled before it is frobnobulated. You could imagine that she has enough pull to insist on treating her Widgets exactly as she pleases, but that's not the hypothesis here. (After all in that case she could just have her own entry URI.) It's much better to use media types, link relations, etc. to let the client implicitly learn the information it needs to know every time it needs to know it.
cbau 12y ago
Nested URLs are useful to signify partonomy. If you delete an artist, you would expect his or her albums to be deleted as well. Versus, if you delete an album, you wouldn't expect the artist to be deleted. And for completely unrelated things (which both would sit at the top level), again you wouldn't expect a cascading delete either.