4 ms·

I'd say maybe half of these are actual good practices. In my experience, these are not: I agree that keeping resource names consistent is good, but using plura

I'd say maybe half of these are actual good practices. In my experience, these are not: I agree that keeping resource names consistent is good, but using plurals is not the only, and probably not the superior, solution. Versioning is an idea that gets talked about a lot but can easily create more problems than it solves. Small improvements in APIs should be backward compatible and major ones should be new APIs. Whatever you do, putting "v1" in the middle of your URL is the wrong way to do it. (And so is putting "api" in your URL. It's better to keep your URLs clean of ambiguous and redundant information.) Nesting resources is an anti-pattern that quickly creates a mess. I've learned this the hard way so please don't repeat my mistakes. The 3rd principle of REST interface constraints is "descriptive" error messages. It is better to be clear and thorough than consistent. Consistency gets you nothing, especially if it is consistently bad.

hesselink 12y ago
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.
jayvanguard 12y ago
If you are building a web service for the general public that you want to last forever (e.g. an interface to Wikipedia or something), follow theoretical REST principles and you'll be well served. If you have actual paying customers that you'll need to support over many years then version your API. Paying customers won't tolerate API breakage and you can't always force them to update on your schedule. Assuming you still want to evolve the API and also sign up new customers, you'll quickly find out you'll need versioning.

hesselink 12y ago

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.

jayvanguard 12y ago

If you are building a web service for the general public that you want to last forever (e.g. an interface to Wikipedia or something), follow theoretical REST principles and you'll be well served. If you have actual paying customers that you'll need to support over many years then version your API. Paying customers won't tolerate API breakage and you can't always force them to update on your schedule. Assuming you still want to evolve the API and also sign up new customers, you'll quickly find out you'll need versioning.