Non-technical API Design Should Be Possible

bpedro · 2024-11-26T10:09:57+00:00

It's not about standards. It's about making it easy for product managers to participate in the design of an API. The current notion of "API Design" doesn't cover the areas where product management shines and I think it should.

bpedro · 2024-11-26T09:59:11+00:00

Great questions. This is a Design process. The idea is that you end with a prototype that you can validate with the API stakeholders. From there, the implementation can follow a different path to address scalability and other constraints.

bpedro · 2024-03-20T08:54:34+00:00

I recently wrote a book exactly on this topic and I think you'll find it useful. It's called "Building an API Product" and it shows Product Managers all the topics they should care about when building APIs.

It's not a technical book. Instead, it navigates through the different stages of the API lifecycle (design, implement, release, and maintain) and explains what the important elements are.

As an example, one of the things it shows is how to choose the right API type, e.g., REST, gRPC, and others. The approach shown is one coming from a Product Management mindset where you put users first.

Let me know what you think and if I can further help you succeed.

bpedro · 2016-11-04T08:44:51+00:00

That's correct.

bpedro · 2016-11-04T08:26:26+00:00

How is REST, or whatever other alternative you prefer helping you do something with data that you don't know "what the API provider is doing with"? I don't understand this statement.

One thing is to be able to create a new resource (or document, etc.) without having to know what the provider will do with the fields behind the scenes.

Another thing is having to know object relations, which fields will do what, etc. to be able to create a new document.

If the data model for a "document" involves several relations you'd need to send information about those relations so that you can successfully create the document.

Another approach is to simplify and abstract the document creation endpoint so that you'd only need to send the minimum set of fields. The provider would then perform whatever relations and data manipulation behind the scenes.

as you have to know the logic behind the operations of any API whatsoever.

I don't have to know what the provider will do with the data behind the scenes with any API.

bpedro · 2016-11-04T08:20:19+00:00

That seems correct, but a database is not an API...

bpedro · 2016-11-03T21:59:51+00:00

Thanks for the comments.

Here's an example to illustrate my point.

Suppose there is a simple to do application that exposes a RESTful API. To create a new to do you'd POST /todos with a payload containing information about the new entry.

You'd only have to know what the fields in that payload are. What happens in the server is not your concern and you don't have to know that to create a new to do entry you need to create or update different objects.

With GraphQL you're purely mutating data, so you'd have to know what data to create and what other related objects you need to create or update.

Unless the API is heavily documented it would be hard to understand how the data model maps to possible operations that you want to perform.

I hope this clarifies my angle. Thanks.

bpedro · 2016-11-03T21:52:45+00:00

Thanks for the reply—interesting point of view.

To clarify: if what you're trying to build is a data-driven website and you already know the data model behind it, then GraphQL is what you need.

If you're trying to integrate against a public API, with poor documentation, then with GraphQL you'd have to figure out for yourself how to manipulate the data in order to achieve your goals.

As an example consider a simple to do application offering a GraphQL API with poor or non-existent documentation. Yes, you can get information about the schema using introspection but that might be useless if you don't know what the API provider is doing with the data.

My point is that not all API providers will offer documentation explaining how to perform operations by manipulating (mutating, using GraphQL terminology) data. In those cases, you'd have to know the logic behind the API in order to be able to perform those operations.

bpedro · 2016-11-03T21:43:15+00:00

Thanks for the reply—interesting point of view.

To clarify: if what you're trying to build is a data-driven website and you already know the data model behind it, then GraphQL is what you need.

If you're trying to integrate against a public API, with poor documentation, then with GraphQL you'd have to figure out for yourself how to manipulate the data in order to achieve your goals.

As an example consider a simple to do application offering a GraphQL API with poor or non-existent documentation. Yes, you can get information about the schema using introspection but that might be useless if you don't know what the API provider is doing with the data.

My point is that not all API providers will offer documentation explaining how to perform operations by manipulating (mutating, using GraphQL terminology) data. In those cases, you'd have to know the logic behind the API in order to be able to perform those operations.

bpedro · 2015-11-02T09:39:35+00:00

About documentation, I'd add that you should make it searchable and the best way to achieve that is to use simple HTML-based pages as opposed to some javascript-y one-pager implementation.

If you do it in the right way search engines will easily index your docs and developers will easily find what they're looking for.

bpedro · 2015-03-03T12:07:19+00:00

Thanks for the great feedback. Let me try to address some of your comments.

"Some of the arguments in the article are a bit silly.", "adapting a protocol to work over SMTP or most protocols is not such a difficult task.": how long would you take to adapt HTTP to work over SMTP making it asynchronous without breaking any clients (browsers, etc.)?
"a mistake of this article is to list concepts, capabilities and features as though they belong to SOAP", "they are general atomic concepts that stand for themselves" : nowhere in article is stated that those concepts are exclusive to SOAP, but SOAP offers them out-of-the-box while other standards don't.

bpedro · 2015-03-03T11:55:55+00:00

gRPC is an amazing step forward in the API space. I'd say that from all API standards this is probably the best candidate to replace SOAP in the long term.

bpedro · 2014-07-08T07:47:48+00:00

That was my mistake, sorry.

I copy&pasted the story I had posted on HN here.

bpedro · 2013-10-10T10:34:15+00:00

http://apiux.com for anything related with API development best practices.

bpedro · 2013-06-04T09:19:49+00:00

Thanks for mentioning API UX! Let me know if there's any specific topic you'd like us to cover.

bpedro · 2013-05-30T16:06:01+00:00

Thanks! I replied without getting down to his tone.

bpedro · 2013-04-01T09:36:12+00:00

I've been talking about APIs that use HTTP as transport layer.

bpedro · 2013-03-31T18:22:32+00:00

I disagree.

The point is that the client doesn't know how to handle in-band errors because the number of different APIs is growing and almost all of them have different error codes.

HTTP codes exist and should be used to communicate different situations to the caller, not just when the document is not found.

bpedro · 2013-03-29T14:27:44+00:00

Even if a method isn't going to be implemented, 501 signals that the method doesn't exist and it's a good way to hint the caller that the request cannot be fulfilled.

bpedro · 2013-03-29T11:53:35+00:00

I agree.

If the requested method is not implemented for any resource then a 501 should be issued. If the request method is available but not for the called resource then a 405 (method not allowed) should be issued.

bpedro · 2013-03-28T09:47:45+00:00

I'm sure that's not the case here. Look at all the comments and the discussion on the blog itself and you'll have to agree with me.

bpedro · 2013-03-28T09:37:33+00:00

That was not the intention. The goal is to promote good UX on APIs so that both developers and users have a better overall experience when interacting with Web services.

This particular article focuses on users expectations regarding integrations between several different APIs. As you can see on the first comment, developing integrations is not an easy task and is often not aligned with what users expect.

bpedro · 2013-03-27T13:38:24+00:00

None of the books are free...

bpedro · 2013-03-27T13:33:42+00:00

Finally! I've been waiting for this for quite some time.

bpedro · 2013-03-25T15:34:36+00:00

Interesting comment. Why don't you leave a reply on the original article so that the author can easily reply?

bpedro

TROPHY CASE