5 ms·

Code can follow links as well, as long as the semantics doesn't change. Aside from versioning through mimetypes, which I believe is a really bad idea, I find H

Code can follow links as well, as long as the semantics doesn't change. Aside from versioning through mimetypes, which I believe is a really bad idea, I find HATEOAS to be a beautiful concept, although not very useful in practice. It's a good place to start though. Trying to design for that can help you shape your API properly, just like SOLID or TDD can do for code.

mateo411 10y ago
Why do you think versioning through mimetypes is a bad idea?
- johnjuuljensen 10y ago
  I should probably have moderated that statement, but mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar. Versioning through the url and versioning through mimetypes requires the same amount of work from the user, but the former is a lot simpler. If you then also take into account, that many http clients have poor support for manipulating headers (SAP and PowerShell (earlier version) for instance), then choosing mimetype versioning makes it harder (impossible) for your users.
  - mateo411 10y ago
    I also prefer putting the version in URL. I find it to be practical and easy way to version your API. I've also been told that it's not the right way to do it.
    - scaryclam 10y ago
      There's no "right" or "wrong" way tp version APIs. There's only peoples opinions. I'd suggest that if someone is saying you're doing it wrong by putting it in the url, you should probably learn to ignore them as they can't tell the difference between their own preference and facts.
  - JimDabell 10y ago
    > mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar. That also rules out using any HTTP method other than GET. The browser address bar doesn't seem relevant here, and if it were, then it would rule out the vast majority of APIs. Versioning through the URL breaks interoperability of clients using different protocol versions. 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.
    - johnjuuljensen 10y ago
      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.

mateo411 10y ago

Why do you think versioning through mimetypes is a bad idea?

johnjuuljensen 10y ago
I should probably have moderated that statement, but mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar. Versioning through the url and versioning through mimetypes requires the same amount of work from the user, but the former is a lot simpler. If you then also take into account, that many http clients have poor support for manipulating headers (SAP and PowerShell (earlier version) for instance), then choosing mimetype versioning makes it harder (impossible) for your users.
- mateo411 10y ago
  I also prefer putting the version in URL. I find it to be practical and easy way to version your API. I've also been told that it's not the right way to do it.
  - scaryclam 10y ago
    There's no "right" or "wrong" way tp version APIs. There's only peoples opinions. I'd suggest that if someone is saying you're doing it wrong by putting it in the url, you should probably learn to ignore them as they can't tell the difference between their own preference and facts.
- JimDabell 10y ago
  > mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar. That also rules out using any HTTP method other than GET. The browser address bar doesn't seem relevant here, and if it were, then it would rule out the vast majority of APIs. Versioning through the URL breaks interoperability of clients using different protocol versions. 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.
  - johnjuuljensen 10y ago
    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.