4 ms·

> Applications that use HTTP are encouraged to allow an arbitrary URL to be used as that entry point. For example, rather than specifying "the initial document

> Applications that use HTTP are encouraged to allow an arbitrary URL to be used as that entry point. For example, rather than specifying "the initial document is at "/foo/v1", they should allow a deployment to use any URL as the entry point for the application. Is this really saying that, for example, I shouldn't have an API specification that says "to fetch a list of users", send a GET to `/api/v3/users`? What's the alternative?

paulddraper 8y ago
Hypermedia [1] As The Engine Of Application State (HATEOAS) https://en.wikipedia.org/wiki/HATEOAS https://en.wikipedia.org/wiki/HATEOAS I not particularly a fan, but it's fairly common. It was popularized as one of the pillars of the REST paradigm. [1] https://en.wikipedia.org/wiki/Hypermedia https://en.wikipedia.org/wiki/Hypermedia [2] https://en.wikipedia.org/wiki/HATEOAS https://en.wikipedia.org/wiki/HATEOAS
- nickik 8y ago
  Is it actually common? Its talked about a lot, however in practice it is not used much from what I can tell.
  - paulddraper 8y ago
    For starters, HATEOAS it's used as the foundation of the most common networked applications in the world: web browsers. Paypal uses it for their API. But yeah, it's kind of like functional programming: the ideas are super common and well understood. But by the numbers, the less pure imperative programming paradigm is overwhelmingly more commonplace.
JoshTriplett 8y ago
API servers may need to co-exist, by mounting them into a hierarchy. You can certainly have `/api/v3/users`, but you should have enough configurability to support mounting that under `/yourapp/api/v3/users` so that someone doesn't need to rewrite URLs in a proxy.
geocar 8y ago
One standout: Service discovery. OpenID Connect[1] for example publishes an endpoint discovery document. This is much easier than building a versioning-layer into your application router. [1]: http://openid.net/specs/openid-connect-discovery-1_0.html http://openid.net/specs/openid-connect-discovery-1_0.html This is also good to combine with requiring users retry and use multiple endpoints. This way you don't have to take risks with DNS and global routing failures potentially breaking your application. If you use TLS to protect your application, I recommend further (randomly) generating a bad SSL certificate to make sure clients retry (and get a good one) so that you can detect anyone stupid enough to take advice like this[2] [2]: http://web.archive.org/web/20120317165131/http://forum.developers.facebook.net/viewtopic.php?pid=258460 http://web.archive.org/web/20120317165131/http://forum.devel...
- antpls 8y ago
  > for example publishes an endpoint discovery document. This is much easier than building a versioning-layer into your application router. How is that different than having only 1 version of the API and updating it? Clients code will still break if a structural data change is pushed (for example, removing a field from the responses)
  - geocar 8y ago
    (Perhaps a question for the mods: Why are so many of antpls's comments flagged/dead? Their other behaviour doesn't seem malicious, and this seems like a reasonable question to me even if it doesn't directly address my comment.) > How is that different than having only 1 version of the API and updating it? Using a service discovery document makes it easier to put /v1 and /v2 on separate servers/domains instead of putting both on all the servers/domains. Serving the service discovery document is cheaper than having your front-end server route all requests to backend systems (like using nginx or an Amazon ELB in application mode). Putting applications on different domains is desirable if /v2 has performance gains (or cost gains) obtained by using the new protocol. Or if they're separate codebases. > Clients code will still break if a structural data change is pushed (for example, removing a field from the responses) It's very difficult to predict how a client will react if you haven't seen/vetted their implementation, but there are things we can do that go beyond service discovery. For example: My advertising service allows publishers (people who make web pages and content) to choose how to render my advertisers' ads in those pages. They do this via a server-side call -- I don't do any tracking of this, but I want to be sure that the client is doing the right thing because I'm still representing the brands. I can look at the web page and sign off on it, but I want to make sure that it'll support a wide range of ads -- including ones I haven't thought of. So I put a lot of energy into patterns like fuzzing the clients, and doing things that I hope will require they do things securely: - I require retries so users always get an ad - I randomly giving them a bad SSL certificate -- one that if they accept, I block their account. I usually only do this during onboarding or for my crawlers (recognised by IP) which check for sneaky stuff. - I require certain utf8 characters to make sure the query is utf8 encoded - I randomly insert random fields to make sure I can add new ones later - I randomly reorder fields in the response to make sure they're not counting I think that if you do all these things, and perhaps other things, and clients are used to it then you probably can have just one version of the API and update it. But this is hard work, and the enterprise is not (in my experience) very fond of hard work.

paulddraper 8y ago

Hypermedia [1] As The Engine Of Application State (HATEOAS) https://en.wikipedia.org/wiki/HATEOAS https://en.wikipedia.org/wiki/HATEOAS I not particularly a fan, but it's fairly common. It was popularized as one of the pillars of the REST paradigm. [1] https://en.wikipedia.org/wiki/Hypermedia https://en.wikipedia.org/wiki/Hypermedia [2] https://en.wikipedia.org/wiki/HATEOAS https://en.wikipedia.org/wiki/HATEOAS

nickik 8y ago
Is it actually common? Its talked about a lot, however in practice it is not used much from what I can tell.
- paulddraper 8y ago
  For starters, HATEOAS it's used as the foundation of the most common networked applications in the world: web browsers. Paypal uses it for their API. But yeah, it's kind of like functional programming: the ideas are super common and well understood. But by the numbers, the less pure imperative programming paradigm is overwhelmingly more commonplace.

JoshTriplett 8y ago

API servers may need to co-exist, by mounting them into a hierarchy. You can certainly have `/api/v3/users`, but you should have enough configurability to support mounting that under `/yourapp/api/v3/users` so that someone doesn't need to rewrite URLs in a proxy.

geocar 8y ago

One standout: Service discovery. OpenID Connect[1] for example publishes an endpoint discovery document. This is much easier than building a versioning-layer into your application router. [1]: http://openid.net/specs/openid-connect-discovery-1_0.html http://openid.net/specs/openid-connect-discovery-1_0.html This is also good to combine with requiring users retry and use multiple endpoints. This way you don't have to take risks with DNS and global routing failures potentially breaking your application. If you use TLS to protect your application, I recommend further (randomly) generating a bad SSL certificate to make sure clients retry (and get a good one) so that you can detect anyone stupid enough to take advice like this[2] [2]: http://web.archive.org/web/20120317165131/http://forum.developers.facebook.net/viewtopic.php?pid=258460 http://web.archive.org/web/20120317165131/http://forum.devel...

antpls 8y ago
> for example publishes an endpoint discovery document. This is much easier than building a versioning-layer into your application router. How is that different than having only 1 version of the API and updating it? Clients code will still break if a structural data change is pushed (for example, removing a field from the responses)
- geocar 8y ago
  (Perhaps a question for the mods: Why are so many of antpls's comments flagged/dead? Their other behaviour doesn't seem malicious, and this seems like a reasonable question to me even if it doesn't directly address my comment.) > How is that different than having only 1 version of the API and updating it? Using a service discovery document makes it easier to put /v1 and /v2 on separate servers/domains instead of putting both on all the servers/domains. Serving the service discovery document is cheaper than having your front-end server route all requests to backend systems (like using nginx or an Amazon ELB in application mode). Putting applications on different domains is desirable if /v2 has performance gains (or cost gains) obtained by using the new protocol. Or if they're separate codebases. > Clients code will still break if a structural data change is pushed (for example, removing a field from the responses) It's very difficult to predict how a client will react if you haven't seen/vetted their implementation, but there are things we can do that go beyond service discovery. For example: My advertising service allows publishers (people who make web pages and content) to choose how to render my advertisers' ads in those pages. They do this via a server-side call -- I don't do any tracking of this, but I want to be sure that the client is doing the right thing because I'm still representing the brands. I can look at the web page and sign off on it, but I want to make sure that it'll support a wide range of ads -- including ones I haven't thought of. So I put a lot of energy into patterns like fuzzing the clients, and doing things that I hope will require they do things securely: - I require retries so users always get an ad - I randomly giving them a bad SSL certificate -- one that if they accept, I block their account. I usually only do this during onboarding or for my crawlers (recognised by IP) which check for sneaky stuff. - I require certain utf8 characters to make sure the query is utf8 encoded - I randomly insert random fields to make sure I can add new ones later - I randomly reorder fields in the response to make sure they're not counting I think that if you do all these things, and perhaps other things, and clients are used to it then you probably can have just one version of the API and update it. But this is hard work, and the enterprise is not (in my experience) very fond of hard work.