Last month we organized our first-ever API Meetup event in San Francisco, California. We were joined by some really interesting figures from the API Space, all of who had something exciting to offer.
Kin Lane (The API Evangelist), Nicholas Grenie (Developer Advocate at Typeform), and Nauman Ali, Product Manager at APIMatic, spoke at the event and presented their talks on topics revolving around API Documentation and Developer Experience.
We’ll summarize these talks and will discuss the key takeaways below.
To go through the talks in detail, you can always visit our YouTube channel and subscribe to our updates while you are at it ?
1. From API to beautiful HX — Nicholas Grenie
Nicholas started off talking about Typeform, what they do, how they do it, and how they leveraged user experience to dominate their niche. He talked about their journey from a monolith to a microservices architecture.
He told us how Typeform was built upon a PHP + MySQL back end, which made it difficult for them to scale or make UI changes, and how Data Migration used to break the whole thing.
He explained how they moved to an API-based internal infrastructure, how they broke down their internal system into bits and pieces, and all key domains into separate micro-services. Typeform’s UI now is completely independent of logic and makes API calls whenever necessary. To make the transformation they adopted Go Language and Node JS, which according to them will ensure they keep on evolving with coming technology and needs. The tool is now completely revamped, the front end is now done in React and all that became possible with the decoupling microservices architecture has to offer.
One hiccup experienced with the model was too many API calls being made by the UI which led to performance issues, for this they formed an internal framework called BFF, Backend for Front End. It’s a layer that sits between the UI and the APIs and makes consolidated calls whenever necessary, converting thousands of calls into one. This produces a very optimized payload.
He further talked about Spec-first development and how it helped Typeform streamline and align its development process. OpenAPI is what they use, for its immense flexibility. Nicholas also demonstrated Typeform’s documentation portals for both internal and public APIs.
2. Automating The API Developer Experience — Nauman Ali
Nauman talked about the Automating the Developer Experience when it comes to APIs. Developer Experience has become sort of an expectation and companies who do not invest enough in it will suffer. The talk further elaborated on what constitutes a good Developer Experience, ranked in order:
- Getting Started Guides
- API Key Management/Authentication
- Client Libraries
- Dynamic Code Samples
- Sandbox, Mocking
- Change Logs
- Reporting, Monitoring
He further talked about API Developers and API Consumers and how the correct Developer Experience optimizes the output for both of them. A demo of APIMatic conveyed how you can automate your API process using our offerings at different stages of the API Development Lifecycle.
The talk was concluded talking about APIMatic’s road-map towards perfect Developer Experience which included:
- Automatic Changelogs and Notification Services
- Analytics Dashboard
- Marketplace with mashed up SDKs and Documentation
- GraphQL support
- Self Service for API Key Management
- Custom Pages
3. Do you have a Pipeline for API Documentation? — Kin Lane
Kin Lane started off with a very simple but important question: “Do you have a Consistent API Lifecycle?”
According to him, your API Life cycle should be consistent in a way that will help you scale your APIs. He emphasized the importance of using API definitions, according to him every microservice life cycle should begin with and be governed by its definition. Following that, he emphasized upon:
- Managing Repos
- API Design Plans
- Versioning Plans
All of which are very important and give a solid foundation to your API Lifecycle. He then talked about the importance of mocking, sandbox environments, running virtual tests on your API, and then iterating upon the results you get.
He also talked about deployment, serverless gateways are making the wave and that’s something that interests him a lot. Portals with interactive documentation, according to him, should also be integrated into your documentation pipeline. Having an auth plan is also important, decide between simple auths and oauths depending on your need and requirements. Having a management layer is crucial, whether it’s APIGEE, Google, Tibco, Kong, or AWS. So is having a monetization strategy, it’s important to plan out the cost of running your API and translate it into billing plans.
Kin Lane also really emphasized upon the importance of auto generating SDKS from your OpenAPI descriptions and strictly advised against hand coding or hand managing SDKs. Also in his words:
“I can’t articulate the quality of SDKs coming out of APIMAtic, I have seen them evolve, I have seen what comes out of Swagger Code Gen vs APIMAtic and they don’t compete.”
Following which he talked about integrating feedback into your road maps and most importantly having a road map in the first place. Making your road map public & communicating with your users and potentials users through it is really important.