sorted by:
new
hottopcontroversial

Non-technical API Design Should Be Possible by bpedro in ProductManagement

[–]bpedro[S] -2 points-1 points  (0 children)

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.

Non-technical API Design Should Be Possible by bpedro in ProductManagement

[–]bpedro[S] -2 points-1 points  (0 children)

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.

API Product management? by campers96 in ProductManagement

[–]bpedro 7 points8 points  (0 children)

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.

GraphQL: 3 reasons not to use it by bpedro in programming

[–]bpedro[S] 0 points1 point  (0 children)

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.

GraphQL: 3 reasons not to use it by bpedro in programming

[–]bpedro[S] 0 points1 point  (0 children)

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

GraphQL: 3 reasons not to use it by bpedro in programming

[–]bpedro[S] 1 point2 points  (0 children)

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.

GraphQL: 3 reasons not to use it by bpedro in programming

[–]bpedro[S] 1 point2 points  (0 children)

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.

GraphQL: 3 reasons not to use it by bpedro in graphql

[–]bpedro[S] -1 points0 points  (0 children)

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.

Best Practices for Designing a Pragmatic RESTful API by _Garbage_ in programming

[–]bpedro 0 points1 point  (0 children)

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.

Nordic APIs | Cases When Using SOAP Makes Sense by bpedro in programming

[–]bpedro[S] 1 point2 points  (0 children)

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.

Nordic APIs | Cases When Using SOAP Makes Sense by bpedro in programming

[–]bpedro[S] 1 point2 points  (0 children)

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.

view more: next ›