11–20 of 21 posts
Stripe has probably the best and cleanest API design.
https://stripe.com/docs/api/balance/balance_object?lang=pyth...
Personally, for building a client library I'd take a look at OpenAPI Generator ( https://github.com/openapitools/openapi-generator ) or Swagger Codegen ( https://github.com/swagger-api/swagger-codegen ) - especially if the API provider has an official OpenAPI/Swagger specification. (If not you can always write a specification yourself). Both tools support PHP among other languages.
Personally, for building a client library I'd take a look at OpenAPI Generator ( https://github.com/openapitools/openapi-generator ) or Swagger Codegen ( https://github.com/swagger-api/swagger-codegen ) - especially if the API provider has an official OpenAPI/Swagger specification. (If not you can always write a specification yourself). Both tools support PHP among other languages.
I must say, however, that it may work for simple APIs but even then usually only for generating the model part and not the API part. What kind of worked for me though was generating code for the server in form of a Kotlin interface for a Spring MVC controller. Although, here too, I had to modify the code generator templates to tailor it to my needs.
Regarding API client, when you can successfully generate an API client with code generation, it should be considered a low-level API client upon which one should build a high-level and more user-friendly API client (e.g. object model with actual methods and not only anemic objects).
I'd highly recommend Josh Bloch's writings. Josh is perhaps best known for the book Effective Java and the Java Collections library. Here is a paper he wrote about good API design (https://dl.acm.org/doi/abs/10.1145/1176617.1176622) and a short interview with him about API design (https://www.infoq.com/articles/API-Design-Joshua-Bloch/).
Brad Myers at CMU also has done research on API usability. See here for more details: http://www.cs.cmu.edu/~NatProg/apiusability.html
Lastly, if you're doing anything remotely related to security, I'd also recommend Matthew Smith's research. He's studied a lot about weaknesses of today's API designs and how they have led to security vulnerabilities. https://ieeexplore.ieee.org/abstract/document/7676144
Worse he doesn’t seem to do any data validation, I recently passed an index instead of an id for one field and ended up with tons of test data that’s broken. Not because of a bug in my code mind you, but because I misunderstood the cryptic comment.
Lastly, he occasionally asks the mobile apps to do processing of the data that’s more easily and safely done on the server. It’s like he misunderstands the role and value of the server in a client server application.
But again he’s my client so I have to be gentle.
Stripe has probably the best and cleanest API design.
And documentation. I would spend some time really understanding their docs and client libraries if you want to see a real world example of the most developer friendly docs available. https://stripe.com/docs/api https://stripe.com/docs/api/balance/balance_object?lang=pyth...
Write automated tests to hit each part of your API and test the functionality of each thing in isolation. If you find the tests frustrating to write, your users will find the API frustrating to use.
I've written more about this here:
https://bad-code-considered-harmful.blogspot.com/2020/05/tes...
By the way, I am not an advocate for TDD. I write my tests at the point when I'm ready to start running them. But I strongly agree with the general claim that TDD makes that says that good unit tests are the closest thing to a panacea you will ever encounter in software development. However, I've also seen projects where the unit tests were just more bloat. Unit tests need to be written to test your API to help you design a better API.
Earlier quoted context omitted.
And documentation. I would spend some time really understanding their docs and client libraries if you want to see a real world example of the most developer friendly docs available. https://stripe.com/docs/api https://stripe.com/docs/api/balance/balance_object?lang=pyth...
Is there any documentation of the client libraries themselves, or just the API?
https://stripe.com/docs/api/balance/balance_retrieve?lang=py...
The client libraries have stand alone documentation as well.
I would also highly recommend to use the spec to dynamically construct your requests. I don't know if PHP has libraries to assist with that, but for example in Python you could use tools like Bravado or Pyotr client.