What do you do when you approach a new API?
As I explore a new API, I have many questions to answer. I need to know the protocols, endpoints, versions, methods, login process, API reference guide, client libraries, batch requests, paged responses, quota handling, and more. I'm taking you through my journey to get the answers I need. Join me in exploring this new API!
Exploring a New API: My Journey to Find Answers
By Michael Levin
Monday, March 20, 2023
When approaching an API you haven’t used before for the first time, what happens? Well, you’ll have a few questions. They go something like:
- http or https, right?
- Endpoint or endpoints?
- Issues regarding multiple endpoints?
- Versions? What I need to know?
GET or POST method?
- Before even login, what can you do?
- Is there non-logged-in services? Like Facebook Graph
- Is there a playground? (sample database, no quotas?)
- Okay, let’s talk about login. Process?
- Are tokens, API keys or other exchanges involved?
- Will I be handing something back on every request?
- Are there client libraries to do this, or am I expected to?
- Is it using one of the conventions like OAuth2?
- Other special things I need to know like CRC checksums (what’s weird?)
- Once logged in, are there logged in service discovery services?
- What’s the protocols?
- If JSON, complexity? The gist?
- Are requests JSON or just responses?
- CSV-ish? Parsing characters?
- API Reference guide?
- Again, the client library question
- Languages client libraries are available in
- Libraries, aside what’s the protocols? JSON-centric? CSV-ish?
- Batch requests?
- Paged responses?
- Quota handling? Is there a credit system?
- Always http request/response?
- Is there any services that are retrieve-later or emailed?
- Other “is there weird stuff” here.
- Strange datatypes or object structures?
- Strong modeling on language, product or design principles?
Okay, those are my thoughts before going in.
My mind is a fresh slate. I only have my recollections of using Moz APIs from time to time over the years. So log in under your old account and poke around.
Consider doing a live session actually using the API screen-sharing.