2024-11-01 - REST API Design - Chewing the Fat 📈

[sethdaily]

Hey programmers,
Today we're talking about API design - Do you know the key principles of REST API Design?

• What’s a good example of a public API you've worked with, and why?
• Any other API design tips you’d recommend?

[ozdemir-mehmet]

First post
The ABS API was pretty good when I last used it, Give options around bulk data egress/ingress. Don't rely on 10 row pagination on a 1,000,000 row dataset

[TobyChurches]

Great topic and very relevant! API design (particularly Rest API's) is super important, making sure that the developer can easily, efficiently and securely access the required data. As for good API's, none really come to mind - Its the bad ones that are memorable. I recently had to work with the Google maps API and hated it. It seemed to be too opinionated for our use case.

[calumjs]

What’s a good example of a public API you've worked with, and why?

The Dynamics API is cool

Any other API design tips you’d recommend?

Return useful error messages with tips on how to fix - this makes it easier to chatgpt it

[drwharris]

What’s a good example of a public API you've worked with, and why?

I loved working with the Stripe API. Well thought out, well structured and well documented.

Any other API design tips you’d recommend?

Try documenting your API before releasing it, its a true sign of how easy your API will be to implement.

[leahy268]

Never built an API. Have gathered data from a few bad and good ones though. The worst I think that I've found so far was the YouTube API. Took me hours to try and understand how to get data from it. Could have been the poor documentation though.

[jeoffreyfischer]

What’s a good example of a public API you've worked with, and why?

None - I only worked with private ones

Any other API design tips you’d recommend?

Return useful error messages for debugging

[joshbermanssw]

What’s a good example of a public API you've worked with, and why?

n/a - only worked with private

Any other API design tips you’d recommend?

Correct error handling, validation and error returning are key!

[StefStar]

I'm not a developer however, I learnt that API's are the backbone of a lot of developer work and not having clear names can easily cause headaches down the line.

[steven0x51]

Any other API design tips you’d recommend?

Error Handling - Use a consistent format, including status codes and error messages gives user better experience and easier to debug

[Lewkans]

What’s a good example of a public API you've worked with, and why?

None - haven't really dealt with public APIs much

Any other API design tips you’d recommend?

Returning relevant and detailed error messages instead of generic error messages for easier debugging in the future.

[Ben0189]

cant think of a good one atm, but Xero API is not great

[RobJT-wq]

I've only used the Microsoft Graph API to automate some SysAdmin tasks, It's pretty easy to work with for my needs.

[Calinator444]

What’s a good example of a public API you've worked with, and why?

I've worked with the ChatGPT completions API. It provides a really robust set of features:

• It actually has a more robust feature set than the ChatGPT web client (e.g. providing a "temperature" field to alter the creativeness of the responses).
• It's got an officially supported Python library that conceals the complexity of the HTTP requests

Any other API design tips you’d recommend?

Use path parameters for retrieving resources and query params for filtering

e.g.

use this api/posts/1

not this api/posts?id=1

[danielmackay]

What’s a good example of a public API you've worked with, and why?

Binance - https://www.binance.com/en-NZ/binance-api

This has great documentation that covers both rest and websocket APIs, and also higher-level general documentation.

Any other API design tips you’d recommend?

No, I put everything I could think of in the rule. 😄

[ricksu978]

What’s a good example of a public API you've worked with, and why?

Clear documentation!

• Stripe: https://docs.stripe.com/api
• Shopify: https://shopify.dev/docs/api

Any other API design tips you’d recommend?

Use colon for custom verbs

https://google.aip.dev/136

[matt-goldman-ssw]

What’s a good example of a public API you've worked with, and why?

NASA

Any other API design tips you’d recommend?

Don't use API keys, use client credentials

[PennyWalker]

This was a great video and excellent for the devs, but I haven't got enough background knowledge to answer these questions :)

[stephanfakossw]

I've learned that I don't know anything about this, so I can't contribute to the discussion...I trust it's an excellent topic for the devs

[AttackOnMorty]

What’s a good example of a public API you've worked with, and why?

Spotify - It has an online playground.
https://developer.spotify.com/documentation/web-api

Any other API design tips you’d recommend?

Documentation

[bahjatalaadelssw]

What’s a good example of a public API you've worked with, and why?
I'm interested in using AI to work with an API
Any other API design tips you’d recommend?
Universal naming conventions

[SamBWagner]

What’s a good example of a public API you've worked with, and why?

• ScryFall! It's awesome
• GitHub

Any other API design tips you’d recommend?

keep your API as flat as you can. No more than 2 layers if you can manage it i.e. /{something}/{something}

[jimmidier]

What’s a good example of a public API you've worked with, and why?

None. Haven't worked on public API yet.

Any other API design tips you’d recommend?

Consistent response format with response code / error code

[thom-wang]

What’s a good example of a public API you've worked with, and why?

I think GitHub's REST API is quite good to work with because it has rich documentation and is beautifully designed meaning every standard a good API should have.

Any other API design tips you’d recommend?

Use GET less and replace it with POST as many as possible, cause it will help to reduce CORS attack.

[babakamyljanovssw]

What’s a good example of a public API you've worked with, and why?

GitHub API, because it is well-documented with useful ready commands for each endpoints and tools to test them out

Any other API design tips you’d recommend?

Standard status code - using status codes that matches outcome: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error

Error handling - helpful error messages can help to understand what went wrong

[jerryluossw]

Any other API design tips you’d recommend?

• A simple consistent response format
• Use PUT and DELETE cautiously, as many organizations’ security policies may block them by default

[vladislav-kir]

What’s a good example of a public API you've worked with, and why?

Modern eCommerce Gateways such as Stripe and Square, Microsoft Graph API, Dynamics 365 API - they have follow most of the tips and have a great documentation. Although, for Dynamics 365 API query string parameters can get very long and messy....

Any other API design tips you’d recommend?

Good error handling - clearly explain what the problem is with the request.

[JeanThirion]

What’s a good example of a public API you've worked with, and why?

https://radarr.video/docs/api/
(same for Sonarr and all the rr's)

Very clear documentation, accessible logs, ...
MSGraph is pretty good too to be honest !

[PothieuG]

What’s a good example of a public API you've worked with, and why?

Github API is very good and well documented!

[ozairashfaqueSSW]

What’s a good example of a public API you've worked with, and why?

None - I only worked with the private ones.

Any other API design tips you’d recommend?

Error handling - Provide clear, structured error responses with relevant HTTP status codes and helpful messages to guide clients in resolving issues.

[tino-liu]

What’s a good example of a public API you've worked with, and why?

None - Only worked on private ones

Any other API design tips you’d recommend?

Recent work taught me that clear error handling and logging them is crucial