4 ms·

After reading the article you linked in another sibling comment's response, can you point to an example of what a true RESTful service looks like. I see how un

After reading the article you linked in another sibling comment's response, can you point to an example of what a true RESTful service looks like. I see how under that definition an API can't be RESTful, but what service then can be? And how do clients interact with it?

virtualmic 4y ago
> can you point to an example of what a true RESTful service looks like. Not OP, but there was an interesting article & discussion recently here: https://news.ycombinator.com/item?id=32141027 https://news.ycombinator.com/item?id=32141027
iio7 4y ago
Basically a normal HTML website, that's true REST.
- bern4444 4y ago
  So if I made an API that would include in its responses other endpoints that can be hit, would that make it RESTful? An example response could be { name: 'john', nickName: 'johnny', relatedEndpoints: ['/v2/friends', '/v2/jobs/', ...] } Or one could include a link to an Open API spec for the API in the response of every request that details all endpoints available and their parameters/bodies. { name: 'john', nickName: 'johnny', apiSpec: '/v2/open-api-spec' }
  - iio7 4y ago
    No, that would not make it REST. I suspect you didn't read the article thoroughly? If your application needs documentation, i.e. a spec or similar, also referred to by some as a "profile", in order for the client to use your resources beyond the initial root URI, then that is not REST! An API, no matter how you twist or turn it, can never be REST. REST are truly only for manual human consumption, not machines. That is why it is so weird everyone is calling their APIs for REST.
    - bern4444 4y ago
      I read the article fully. If an API response included all the possible actions and information that one takes as a follow up to a previous call, how is that any different from providing the equivalent forms and links to additional information on a web page rendered by a browser? It certainly seems possible to pigeonhole an API into a RESTful architecture but I understand why based on the article, APIs aren't often considered RESTful. But it seems they can be. I see this as a proof by contradiction. I, today, can navigate directly to posts by a friend of mine on a social media site. Auto logged in, not having to enter any form data etc. That's my starting point both in a browser and via API. I'd see their post. Alongside that post I'd see actions I can take: clicking on other friends' profiles, liking the post, commenting on the post, removing the friend etc. Encoding all that in an API might look like this: { name: 'john', userId: '12' nickName: 'johnny', posts: [ { content: 'My funny comment', likes: 3, likedByUserIds: ['13', '14', '15' ], postId: 333 }, { ... } ] relatedEndpoints: [ '/users/12/friends/', : {} '/users/13', : {} '/users/14', : {} '/users/15', : {} '/like/333, : {} '/unlike/333', : {} '/remove-friend/12', : {} '/comment/333/' : { commentText: '' } ... ] } In this way, the response to my request includes all the possible actions I can then take and what data I need to provide to take it (in the example of the comment route). * No consulting of external documentation is needed, all the information is right there. * I can explore another user's profile (people with user ids of 13, 14, and 15), I can like and unlike this post with the `/like/` and `/unlike` routes, I can remove this person from my friends list etc. Including such information makes this response no different than what I can do via browsing the page - all my interactions with the API are directly driven by their responses - not by consuming outside documentation. If all possible actions and their routes were included on route supported by my API, why would this not be RESTful? At the end of the day - this to me is a distinction without a difference. Whether this documentation is defined as part of the response or stored in an OpenAPI spec, the end result is the same - I can easily wire things up together to accomplish my goals. This is where SDKs become more useful. SDKs are fully documented, require no external information for them to be used, contain everything possible that can be done as methods etc. If I get a `User` class back from an SDK - I can then invoke all the methods on that user like - getFriends, getPostById, etc etc. If I call a `getFriendById(12)` method I'd expect a `Friend` instance rather than a more generic `User` instance which should have a `removeFriend` method but no `addFriend` method. That appears equally as RESTful as a website with actions that can be taken.

virtualmic 4y ago

> can you point to an example of what a true RESTful service looks like. Not OP, but there was an interesting article & discussion recently here: https://news.ycombinator.com/item?id=32141027 https://news.ycombinator.com/item?id=32141027

iio7 4y ago

Basically a normal HTML website, that's true REST.

bern4444 4y ago
So if I made an API that would include in its responses other endpoints that can be hit, would that make it RESTful? An example response could be { name: 'john', nickName: 'johnny', relatedEndpoints: ['/v2/friends', '/v2/jobs/', ...] } Or one could include a link to an Open API spec for the API in the response of every request that details all endpoints available and their parameters/bodies. { name: 'john', nickName: 'johnny', apiSpec: '/v2/open-api-spec' }
- iio7 4y ago
  No, that would not make it REST. I suspect you didn't read the article thoroughly? If your application needs documentation, i.e. a spec or similar, also referred to by some as a "profile", in order for the client to use your resources beyond the initial root URI, then that is not REST! An API, no matter how you twist or turn it, can never be REST. REST are truly only for manual human consumption, not machines. That is why it is so weird everyone is calling their APIs for REST.
  - bern4444 4y ago
    I read the article fully. If an API response included all the possible actions and information that one takes as a follow up to a previous call, how is that any different from providing the equivalent forms and links to additional information on a web page rendered by a browser? It certainly seems possible to pigeonhole an API into a RESTful architecture but I understand why based on the article, APIs aren't often considered RESTful. But it seems they can be. I see this as a proof by contradiction. I, today, can navigate directly to posts by a friend of mine on a social media site. Auto logged in, not having to enter any form data etc. That's my starting point both in a browser and via API. I'd see their post. Alongside that post I'd see actions I can take: clicking on other friends' profiles, liking the post, commenting on the post, removing the friend etc. Encoding all that in an API might look like this: { name: 'john', userId: '12' nickName: 'johnny', posts: [ { content: 'My funny comment', likes: 3, likedByUserIds: ['13', '14', '15' ], postId: 333 }, { ... } ] relatedEndpoints: [ '/users/12/friends/', : {} '/users/13', : {} '/users/14', : {} '/users/15', : {} '/like/333, : {} '/unlike/333', : {} '/remove-friend/12', : {} '/comment/333/' : { commentText: '' } ... ] } In this way, the response to my request includes all the possible actions I can then take and what data I need to provide to take it (in the example of the comment route). * No consulting of external documentation is needed, all the information is right there. * I can explore another user's profile (people with user ids of 13, 14, and 15), I can like and unlike this post with the `/like/` and `/unlike` routes, I can remove this person from my friends list etc. Including such information makes this response no different than what I can do via browsing the page - all my interactions with the API are directly driven by their responses - not by consuming outside documentation. If all possible actions and their routes were included on route supported by my API, why would this not be RESTful? At the end of the day - this to me is a distinction without a difference. Whether this documentation is defined as part of the response or stored in an OpenAPI spec, the end result is the same - I can easily wire things up together to accomplish my goals. This is where SDKs become more useful. SDKs are fully documented, require no external information for them to be used, contain everything possible that can be done as methods etc. If I get a `User` class back from an SDK - I can then invoke all the methods on that user like - getFriends, getPostById, etc etc. If I call a `getFriendById(12)` method I'd expect a `Friend` instance rather than a more generic `User` instance which should have a `removeFriend` method but no `addFriend` method. That appears equally as RESTful as a website with actions that can be taken.