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
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! 😅
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.
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.
My answer to this question is definitely "read the documentation". I like to have an intellectual understanding of a new API before using it.
Are you going straight to the API reference or something more like a getting started guide or how to?
My approach:
Basically, Documentation is the key.
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.
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)
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.
I'd start with the docs ... when I see that the docs suck (not that often) I'd try a general google/stackoverflow search.