How do you approach a new API?

If you are using an API for the first time, what's your process around getting started?

Do you find docs to read? Do you look for a getting started guide? Do you dive right in and start trying to make it work?

Does your approach change if you are learning a new protocol like gRPC vs. REST?

And for a bonus question, what was your first protocol experience? Because mine was SOAP!

Photo by Douglas Lopes on Unsplash

Comments

[Jatin Sharma]

My approach:

1. Getting stated guide.
2. If authentication is required then look into it.
3. What do I want from that API? (what things or variables i need from API).
4. Find an endpoint and look it's docs.

Basically, Documentation is the key.

[Amara Graham]

I'm quite similar! I try to look for the path of least resistance - can I do anything without authentication? When I do authenticate, what's a quick and easy win that I can truly validate that the authentication worked as expected.

[Jatin Sharma]

can I do anything without authentication?

It just depends on what API you are using. Some APIs need authentication to provide data other do it without authentication.

If you wanna check that you are authenticated or not then send a request to any endpoint of the API and you'll get the result or error (Depending on your authentication state)

[Euan]

Shortcut: check if it’s using a standard like OData, in which case most of the implementation details will just be convention, and you can then just focus on finding out where the entities you’re looking for are.

[cloutierjo]

Most lib have a short getting started at the beginning of the doc, I usually follow that then move toward the additional concept.

1 big difference between small library and large framework is that usually for a small lib, I'll focus on my reason to use it and directly integrate it in my project. But for larger framework, I'll usually create a small throwable project to follow the guide and apply my learning in a sandboxed project. Then move to the needed concept doing a small poc in that sandbox to finally use it in my real project. I tend to keep the sandbox for a while reusing or sometime when I face challenge with the framework.

As for protocol started with rest went onto soap and back to rest.

[Amara Graham]

But for larger framework, I'll usually create a small throwable project to follow the guide and apply my learning in a sandboxed project.

YES! I do the same thing. I would almost say I do a bit of validation testing on larger frameworks first.

[Adam Crockett 🌀]

Create an OpenAPI document and generate it

[leob]

I'd start with the docs ... when I see that the docs suck (not that often) I'd try a general google/stackoverflow search.

[Amara Graham]

when I see that the docs suck (not that often)

As someone who is directly responsible for my company's docs, this is the goal! Make the docs not suck! 😅

[Bret Bernhoft]

My answer to this question is definitely "read the documentation". I like to have an intellectual understanding of a new API before using it.

[Amara Graham]

Are you going straight to the API reference or something more like a getting started guide or how to?

[Bret Bernhoft]

I am going straight to the API reference.