How would you build an API for third parties?

[maxweber]

Not an API for your own frontend or mobile app, but for third-party developers and business partners. There are plenty of tools and approaches out there. For that reason, I keep my question open and do not mention tools, which I already took a look at.

One important aspect is that the API should support OAuth2 so customers can independently activate third-party integrations.

Thanks, Max

[jr0cket]

1. Use an off-the-shelf API generation tool

If it is not known what customers want (or even the customers don’t know), use a product / OSS tool to generate a GraphQL API over one or more databases (or just part of a database schema)

Pros

• avoids a lot of API design (i.e. no design - also a con as just putting data out there without thinking can be a poor experience for all)
• can be used over databases and REST APIs (depending on product )

Constraints

• can be more of a challenge to use for customers than a well designed API (depends on how well databases are designed relevant to the API)
• can lead to long running queries and other database performance challenges

These products should include OAuth2 or support an external service (e.g via web hook)

I’ve used Hasura on a commercial project to provide this approach. It’s quick and relatively simple, although I didn’t use it out of a well formed choice, so there may be more appropriate solutions.

2. JUXT Site

GitHub - juxt/site: A web and API server, powered by xtdb.com looks like an exciting way to construct an API effectively (on my TODO list)

3. Build a well designed REST API

I find Reitit an excellent tool for building REST APIs quickly, validated with Clojure.spex / Malli

The data driven approach is simple to work with

Reitit support the Ring protocol, providing great support for middleware

Reitit also includes swagger (OpenAPI) support that generates Live API documentation

I’ve used Reitit commercially on several projects and found it very effective and a joy to develop with

4. Combine any of the above

REST and GraphQL each have there strengths and challenges and each can be provided to meet specific needs of customers

[maxweber]

@jr0cket thanks a lot for your answers

Today I found Malcolm’s newest screencast about juxt/site while trying to find out if juxt/yada is still “alive”.

I guess I would need to invest several days to wrap my head around juxt/site. Therefore I’m trying to find an off-the-shelf API generation tool. Hasura looks promising, but it may be too sophisticated for my use case. The planned API would allow third parties to schedule social media posts. But I’m not planning to expose a lot of our database via the API.

In Malcolm’s screencast, I find this slide pretty interesting:

(Building Site: Episode 40 - YouTube)

It’s about that juxt/site can just be used as the “auth server” which handles all the complicated OpenID and OAuth2 things. While the API of your app would just receive a JWT. Buying an “auth server as a service” would greatly reduce the cost of my project. Currently, I’m looking into the following:

(Machine to Machine (M2M) Communication - Auth0)

Sounds like an “auth server as a service”. But the documentation after the sign-up is not super helpful. I’m currently watching a few tutorial videos on Youtube about this feature of auth0.com

[jr0cket]

I used JWT and auth0.com with Hasura, building a web hook for Hasura with Reitit and middleware that decoded JWT tokens.

Hasura can be a bit weird to confirm and has plenty of constraints, but is pretty quick to get something up and running

The web hook code was pretty simple once you get a grasp of how the tokens work and understand which option of aaith0.com to use (I am sure there are other company that provide this sort of service too).

I probably did spend as much time writing a Reitit API (web hook) as I did configuring Hasuras.

If all that is needed is a few endpoints, I’d suggest writing your own using reitit (or compojure if it’s more family to the dev team)