4 ms·

I suspect that we are designing for different clientele. I'm currently in charge of a pretty classic, GET things out, and POST things in API. If my API support

I suspect that we are designing for different clientele. I'm currently in charge of a pretty classic, GET things out, and POST things in API. If my API supports that some non-IT office guy can get his daily report through the browser, and the API at the same time has the power and flexibility needed for someone with IT skills to do more then I've won. Both me and my users gain by me taking extra steps to make it as accessible as possible. I also fail to see how versioning through urls break anything, except if the newer client no longer has support for v1. In both versioning schemes you specify which version of a resource you're sending/wants to receive, in one scheme you do it through a header, in the other through the url. >> If a client using v1 communicates with a client using v2, then they will see two separate sets of resources and they would never have the same identifiers for (what should be) the same resources. Maybe we're defining versioning differently. I strive to make resource types backwards compatible, but if I can't then it's either a new version or a creating a new more specialized resource type for the specific problem.

JimDabell 10y ago
> If my API supports that some non-IT office guy can get his daily report through the browser Most APIs I work with wouldn't work this way even for read-only access because of authentication requirements. I guess you're using something like HTTP digest auth with usernames and passwords? Even so, that still works for your use case as long as your users are happy with a default version. e.g. requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time. I don't think I've ever come across non-IT office guys that have more complex versioning requirements than that. > I also fail to see how versioning through urls break anything, except if the newer client no longer has support for v1. Here's an example: Client A (using version 2), talking to Client B (using version 1): > Here is a friend suggestion for person https://example.com/v2/people/foo https://example.com/v2/people/foo Client B: > Okay, I'll add them to my contacts. My contact list is now: https://example.com/v1/people/foo https://example.com/v2/people/foo (error: cannot parse) Had the URIs truly been identifiers, this would have looked like: Client A (using version 2), talking to Client B (using version 1): > Here is a friend suggestion for person https://example.com/people/foo https://example.com/people/foo Client B: > Hey, I already know that guy! Once you break the identity part of URIs, you start getting a tonne of these awkward problems to work around. URIs are meant to be the primary keys of the web, and you're going against the grain of the medium when you break that. To put it another way, imagine if websites had to change every page URI from /html4/ to /html5/ when they switched versions. That's a whole lot of work and breaking things for no reason. I'd rather follow how the web was designed to work and not create so much extra work.
- johnjuuljensen 10y ago
  >> I guess you're using something like HTTP digest auth with usernames and passwords? Basic auth (over https only) actually, I'm even advocating it. We support expirable tokens as well. >> requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time The only way for me to go would be option 2: requests without a specific version get version 1. Any other choice and I'd have customers API integrations breaking, because many of them would not have specified their version mimetypes correctly and would therefore get the default version, which would at some point diverge from their expectations. >> URIs are meant to be the primary keys of the web, and you're going against the grain of the medium when you break that. In that context your example makes sense, I just don't see that as realistic problem. In real life URI aren't as static as we pretend. How many companies would make sure the resource urls are still valid after changing the company and domain name? The real identifier in your case is "foo" and "people" is the type. Accepting that sets you free to do versioning as you please and to save 90% characters in all ids :) In the end we should design apis for our users, not for our selves. My clients are always non-IT departments, often in enterprisy environments, and if they can get 2-4 hours allocated from IT in the next 6 months to do some API integration, they are lucky. So I design my api for maximum simplicity, and maximum longevity of the using scripts, because if I wanted to make a breaking change, I'd have to wait 6 months before all customers could be expected to have transitioned. Most of my api users couldn't tell you what a mimetype is btw., but a v2 in the url would make complete sense. I get where you're coming from, on our latest api version I started out wanting to do full HATEOAS (Bought and read this great book http://www.designinghypermediaapis.com/ http://www.designinghypermediaapis.com/), but in the end I had too much trouble getting my test customers migrated, so I had to scale back on the desgin goals. Scaling back to what worked for everybody was very informative and the api is now, imo, the better for it. If I need to bump the vesion it'll be with a vx in the url. An id is a simple non-globally unique thing, that you use to build a url etc.
  - JimDabell 10y ago
    > Any other choice and I'd have customers API integrations breaking, because many of them would not have specified their version mimetypes correctly and would therefore get the default version, which would at some point diverge from their expectations. "Some other people might write code that does things incorrectly and then their software might break" is something you can say about any API style, it's nothing special to media type versioning. If many of your customers are writing code that integrates with your API incorrectly, you don't have an API design problem, you have a poor communication problem, and that's going to hurt you in all kinds of ways. > In real life URI aren't as static as we pretend. They are static if you don't deliberately break them; I'm just pointing out some of the consequences if you choose to. > How many companies would make sure the resource urls are still valid after changing the company and domain name? Companies are laser focused on this if they rebrand. Companies love their search rankings. But how common is it to rebrand? Optimise for the common case, not the uncommon ones. > The real identifier in your case is "foo" and "people" is the type. You're turning URIs from an opaque identifier clients can use as-is to a compound structure that clients have to parse, manipulate, and (re)generate. You're putting more logic on the client, and thus giving client developers more rope to hang themselves with immediately after saying they can't be trusted to get things right. This is not designing for maximum simplicity. Designing for maximum simplicity is to have an API that says "here's a link; follow it", not an API that says "here's an ID, generate a URI from it according to these rules we set out in our documentation, that are different for every type of resource". The latter is more work and more error prone.

JimDabell 10y ago

> If my API supports that some non-IT office guy can get his daily report through the browser Most APIs I work with wouldn't work this way even for read-only access because of authentication requirements. I guess you're using something like HTTP digest auth with usernames and passwords? Even so, that still works for your use case as long as your users are happy with a default version. e.g. requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time. I don't think I've ever come across non-IT office guys that have more complex versioning requirements than that. > I also fail to see how versioning through urls break anything, except if the newer client no longer has support for v1. Here's an example: Client A (using version 2), talking to Client B (using version 1): > Here is a friend suggestion for person https://example.com/v2/people/foo https://example.com/v2/people/foo Client B: > Okay, I'll add them to my contacts. My contact list is now: https://example.com/v1/people/foo https://example.com/v2/people/foo (error: cannot parse) Had the URIs truly been identifiers, this would have looked like: Client A (using version 2), talking to Client B (using version 1): > Here is a friend suggestion for person https://example.com/people/foo https://example.com/people/foo Client B: > Hey, I already know that guy! Once you break the identity part of URIs, you start getting a tonne of these awkward problems to work around. URIs are meant to be the primary keys of the web, and you're going against the grain of the medium when you break that. To put it another way, imagine if websites had to change every page URI from /html4/ to /html5/ when they switched versions. That's a whole lot of work and breaking things for no reason. I'd rather follow how the web was designed to work and not create so much extra work.

johnjuuljensen 10y ago
>> I guess you're using something like HTTP digest auth with usernames and passwords? Basic auth (over https only) actually, I'm even advocating it. We support expirable tokens as well. >> requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time The only way for me to go would be option 2: requests without a specific version get version 1. Any other choice and I'd have customers API integrations breaking, because many of them would not have specified their version mimetypes correctly and would therefore get the default version, which would at some point diverge from their expectations. >> URIs are meant to be the primary keys of the web, and you're going against the grain of the medium when you break that. In that context your example makes sense, I just don't see that as realistic problem. In real life URI aren't as static as we pretend. How many companies would make sure the resource urls are still valid after changing the company and domain name? The real identifier in your case is "foo" and "people" is the type. Accepting that sets you free to do versioning as you please and to save 90% characters in all ids :) In the end we should design apis for our users, not for our selves. My clients are always non-IT departments, often in enterprisy environments, and if they can get 2-4 hours allocated from IT in the next 6 months to do some API integration, they are lucky. So I design my api for maximum simplicity, and maximum longevity of the using scripts, because if I wanted to make a breaking change, I'd have to wait 6 months before all customers could be expected to have transitioned. Most of my api users couldn't tell you what a mimetype is btw., but a v2 in the url would make complete sense. I get where you're coming from, on our latest api version I started out wanting to do full HATEOAS (Bought and read this great book http://www.designinghypermediaapis.com/ http://www.designinghypermediaapis.com/), but in the end I had too much trouble getting my test customers migrated, so I had to scale back on the desgin goals. Scaling back to what worked for everybody was very informative and the api is now, imo, the better for it. If I need to bump the vesion it'll be with a vx in the url. An id is a simple non-globally unique thing, that you use to build a url etc.
- JimDabell 10y ago
  > Any other choice and I'd have customers API integrations breaking, because many of them would not have specified their version mimetypes correctly and would therefore get the default version, which would at some point diverge from their expectations. "Some other people might write code that does things incorrectly and then their software might break" is something you can say about any API style, it's nothing special to media type versioning. If many of your customers are writing code that integrates with your API incorrectly, you don't have an API design problem, you have a poor communication problem, and that's going to hurt you in all kinds of ways. > In real life URI aren't as static as we pretend. They are static if you don't deliberately break them; I'm just pointing out some of the consequences if you choose to. > How many companies would make sure the resource urls are still valid after changing the company and domain name? Companies are laser focused on this if they rebrand. Companies love their search rankings. But how common is it to rebrand? Optimise for the common case, not the uncommon ones. > The real identifier in your case is "foo" and "people" is the type. You're turning URIs from an opaque identifier clients can use as-is to a compound structure that clients have to parse, manipulate, and (re)generate. You're putting more logic on the client, and thus giving client developers more rope to hang themselves with immediately after saying they can't be trusted to get things right. This is not designing for maximum simplicity. Designing for maximum simplicity is to have an API that says "here's a link; follow it", not an API that says "here's an ID, generate a URI from it according to these rules we set out in our documentation, that are different for every type of resource". The latter is more work and more error prone.