Mastodawn

My comfort zone is js/node, and I’ve got a working prototype built with Fastify with some of the OpenAPI plugins. I like the way I can define my API and schema and then instantly plug in to the OpenAPI ecosystem (RapiDoc, Swagger UI, Stoplight, Postman…)

I’ve gone implementation first (ie I made working endpoints and then described and validated them with a schema, and then autogenerated docs). I see many tools (Postman etc) that focus on design/docs first but that seems like it solves a problem I don’t have, and makes new ones?

The ecosystem is dizzying though. To get from prototype to production I know I want to add API keys, rate limiting, etc and later I may want more sophisticated quotas, billing, bot detection etc.

All the cloud players have big complex and pricy offerings that solve some of these problems (but may add more), e.g. Apigee, Azure API gateway etc. Smaller and open source players here are very interesting: e.g. Zuplo, Tyk, Kong etc.

The docs space is equally dizzying: there are classy looking products that only solve a narrow slice of the problem. e.g. Readme.com is slick, but to use their analytics you have to send them data. They don’t solve for API key management or other gateway pieces at all.

Open source solutions like API Umbrella can solve the whole thing, but with less polish, no SLAs, and taking on responsibility for someone else’s esoteric stack choices. I have enough trouble with *my* esoteric stack choices :)

@randometc

1. High Availability.
2. Latency.
3. Security (level depends on dataset).
4. Feature Rich.
5. SDKs.

Then as the company mature: avoiding breaking changes, metrics, etc.

@randometc I would stay away from REST APIs and directly do RPC. Apply common principles (CRUD operations), and benefit from the flexibility. You also get SDKs generated for free.

@xethorn interesting. Would you use gRPC (or GraphQL) or just RPC-ish over HTTP? I remember using XML-RPC back in the day and I think it would require shipping an SDK to make it palatable for most developers.

@randometc gRPC solves a lot of this. Your question about GraphQL is interesting. It depends on your problem space. Are you building your APIs for backend integrations, or for mobile / web clients?

@xethorn backend majority, maybe very simple frontends with 1-3 calls.

@randometc I'd start small (gRPC), then add a GraphQL layer when things become more stable.

Mo Morgan Jan 8, 2023

@randometc This in no way contributes to your question but it reminded me that I only very recently learned that 'table stakes' means the opposite of what I thought.

In vague answer to the question, in the spirit of MVP, I'd err on the side of high-as-possible availability, , detailed-as-possble documentation, few-as-possible (and release-numbered) features.

I appreciate these are probably the least helpful things you'll get back!

@mo no that’s helpful! I didn’t have availability as a v1 goal, but the first two responses have mentioned it. If you were evaluating an API how would you assess availability? Do you just look at SLAs or do you want transparency into error rates, status/uptime/etc?

Mo Morgan Jan 8, 2023

@randometc Errors are more interesting than uptime for me, if I had to choose. It's easier to catch unresponsive endpoints, but harder to cater for outbreaks of weirdness. But I don't know how representative I am, really.

Jonathan Beri Jan 8, 2023

@randometc big question that's missing is who is the consumer? Internal vs external, free or paid service, what kind of client (servers, mobile, web,) are there existing standards to conform to?

@jberi external, free and paid, mostly servers expected to be calling but could be web/mobile as well, totally greenfield

@jberi interested to hear why all that makes a difference though!

Jonathan Beri Jan 8, 2023

@randometc not enough space to go through all the details, unfortunately. But two things those touch on are:

* Are there technical constraints you must align with
* Are there expectations of your consumers

Just some examples of what to consider - Internal APIs either have existing infra and/or people to operate something like Kong. External API need user sign up while internal apps probably HAVE TO use corporate SSO. Web apps are probably all client-side JS, so gRPC is very hard to consume.