My friend was complaining that his iOS engineer made horrible API design decisions. I didn’t feel like I could discuss this intelligently so I started looking up materials on what makes a good API.
on software apis:
At Capsule Health we have followed jsonapi as a way to structure the api. Future directions may include GraphQL and API Gateway.
An interesting topic is what granularity size do you use when choosing your resources. We found that blindly using JSONAPI essentially gives us an API that is no more than a wrapper around a database. Increasingly the (javascript) community has been reevaluating REST as a dogma. Projects like GraphQL and Falcor deviate from strict REST with the goal of allowing clients to be more declarative in their interactions with the backend.
Its great if you invest in a way to interact with your api for members on the mobile team or other services. Technologies like Swagger, RAML and Api Blueprint allow you to spec out apis in a highlevel language and, in some instances, generate production code.
Bonus video:
If you need help solving your business problems with software read how to hire me.