3 ms·

At work we had a team develop a corporate standard for REST APIs that includes discoverability, such as including a 'links' and 'actions' properties on resource

by Osiris 14y ago

At work we had a team develop a corporate standard for REST APIs that includes discoverability, such as including a 'links' and 'actions' properties on resources. Our team determined that implementing the discoverability aspect was going to take a significant amount of engineering resources and wouldn't provide much, if any. The other problem I have with the idea of discoverability in the API is that it doesn't really help the client. For example, with a forum API there may be a link to create a new comment. The client has to be written to recognize the new comment link and attach the URI to a button. What if the API changes the new comment link? How does discoverability help here? Sure, the server is sending the new link but the client doesn't know that new link is really the new comment link that it's expecting so the client has to be updated anyway. So I don't really see how that helps prevent the client from needing updates when the server changes something.

vidarh 14y ago
> Sure, the server is sending the new link but the client doesn't know that new link is really the new comment link that it's expecting so the client has to be updated anyway. Then you're doing it wrong. See the article example. E.g.: <link rel = "/linkrels/entry/newcomment" uri = "/entries/1337/comments" /> The "rel" attribute remains static. You don't change that. It is what tells your client that "this link is a new comment link". The "uri" attribute can change at will. The client knows that "/linkrels/entry/newcomment" means that this is the link to follow to post comments to this entry. It does not need to be updated when the url's to server resources change, as long as the "rel" attributes stay the same.
- Osiris 14y ago
  I was referring to the rel attribute, not the uri. So your point is that once the server establishes a defined API that it can't change in order to maintain compatibility with the client, which is the need for API versioning. So the client still has to be updated when the API changes. I suppose it provides a little flexibility for the API to adjust the endpoints, but in practice it still seems like a bad idea to modify the endpoints because clients could have cached data pointing to existing endpoints that you now break.

by Osiris 14y ago

vidarh 14y ago

> Sure, the server is sending the new link but the client doesn't know that new link is really the new comment link that it's expecting so the client has to be updated anyway. Then you're doing it wrong. See the article example. E.g.: <link rel = "/linkrels/entry/newcomment" uri = "/entries/1337/comments" /> The "rel" attribute remains static. You don't change that. It is what tells your client that "this link is a new comment link". The "uri" attribute can change at will. The client knows that "/linkrels/entry/newcomment" means that this is the link to follow to post comments to this entry. It does not need to be updated when the url's to server resources change, as long as the "rel" attributes stay the same.

Osiris 14y ago
I was referring to the rel attribute, not the uri. So your point is that once the server establishes a defined API that it can't change in order to maintain compatibility with the client, which is the need for API versioning. So the client still has to be updated when the API changes. I suppose it provides a little flexibility for the API to adjust the endpoints, but in practice it still seems like a bad idea to modify the endpoints because clients could have cached data pointing to existing endpoints that you now break.