DEV Community

Cover image for How do you approach a new API?
Amara Graham
Amara Graham

Posted on

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

Latest comments (12)

Collapse
 
euankennedy profile image
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.

Collapse
 
j471n profile image
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.

Collapse
 
missamarakay profile image
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.

Collapse
 
j471n profile image
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)

Collapse
 
adam_cyclones profile image
Adam Crockett ๐ŸŒ€

Create an OpenAPI document and generate it

Collapse
 
bretbernhoft profile image
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.

Collapse
 
missamarakay profile image
Amara Graham

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

Collapse
 
bretbernhoft profile image
Bret Bernhoft

I am going straight to the API reference.

Collapse
 
cloutierjo profile image
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.

Collapse
 
missamarakay profile image
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.

Collapse
 
leob profile image
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.

Collapse
 
missamarakay profile image
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! ๐Ÿ˜