Good examples of REST APIs

Hello,

What are good examples of documented REST APIs that you use as a reference in your API developments?

I very often refer to Stripe or Twilio which are excellent examples and perfectly documented. However, their APIs do not cover all aspects of a real-life app, and sometimes they make "non-REST" concessions.

I sometimes have trouble finding the right REST approach (choosing the right route + method) for simple cases, like authentication for example. I'm usually tempted to use routes such as /login or /register but it just doesn't feel correct REST.

I recently had to implement a two-factor authentication API for a mobile application, but again, it was very difficult to find good examples of such API architecture.

So if you have any good documentation (swagger, postman, ...), Github repos, articles or any other resources that would be useful for designing good REST API, feel free to share them! :)

Cheers,

shez1983

6 years ago

Level 23

i think for normal routes like getting users, products etc do the consistent thing GET /users

for login/register i think that is a convention and easier understood than say POST /users to create a user..

for complicated stuff, be consistent, have standard response structure, the only reason to have a non standard REST route ("non-REST" concessions.) is when you are working with apps as for them doing two API request will be time consuming ie latency issues

maximew

6 years ago

Level 9

Thanks @shez1983, interesting.

I would love to see how some app APIs have solved more complex problems in a REST way. Any idea of documented projects and or open source ones? Not necessarily Laravel!

topvillas

6 years ago

Level 46

Not really answering your question but.

If you're interested in making your APis completely restful the take a look at this excellent talk from Laracon 2017.

https://www.youtube.com/watch?v=MF0jFKvS4SI

Also, have a look at this cool package for exposing your API. Some of the "advantages" of GraphQL but without all the tedious setting up.

#https://laravel-jory.kolenberg.net/docs/3.0/overview

1 like

michaellatham

6 years ago

Level 8

The laravel forge api has a nice structure and documentation https://forge.laravel.com/api-documentation

Regarding sticking to just REST verbs, think about what you're creating/showing, so for logging in some people use session as the subject, i.e Route::post('sessions', 'SessionController@store')

maximew

6 years ago

Level 9

@topvillas Very interesting video indeed, thanks! Will have a look at the package.

@michaellatham Forge documentation is interesting! However, I see many actions like this :

POST /api/v1/servers/{id}/revoke
POST /api/v1/servers/{id}/reconnect
POST /api/v1/servers/{id}/reactivate
POST /api/v1/servers/{id}/mysql/reboot

Is there a reason not to use REST resources for them?

Please or to participate in this conversation.