API the Docs Paris 2018

After being at the first API the Docs conference in Amsterdam in December 2017 and having really enjoyed myself, I quickly decided to attend the second API the Docs conference in Paris, too, immediately after it’s been announced. On top of that, I submitted a last-minute talk proposal and got accepted as a speaker. What I liked most about their first edition was that it’s highly focused on its topic but a small-scale event. In a single-track conference with less than a hundred participants, there’s a strong feeling of community. The second edition fully matched these expectations. My last blog post was well-received by the organizers and the community, so naturally, I had to write one about this event, too.

API the Docs Paris 2018 took place at Mozilla’s Paris location, a historic building in the city, inconspicuous from the outside but impressive on the inside. They have an office with an integrated space for community events and acted as a sponsor for this event by letting the conference use that space for free.

The Talks

The first speaker of the day was Mehdi Medjaoui, who talked about banks and fintechs. Because of PSD2, banks are forced into innovation. He mentioned that Stripe grabbed a $10bn opportunity that the banks missed by making payments really easy for developers. Their investments in Developer Experience are worth it: 90% of Stripe’s customers never contact support. Mehdi showed parts of his research where he compared developer portals from different banks and fintechs and where they shine and where they lack. Positive examples include teller.io, Deutsche Bank APIs, and Capital One DX. A nice feature that some of these APIs have, and that developers like a lot, are user personas, in which test accounts are provided that are fake users but that act like real users in the sandbox with various transaction data.

The second speaker was Kathleen de Roo. She’s part of Pronovix, the main driving force behind API the Docs, and she talked about the role of developer portals, showing off some interesting examples, too. According to her, developer portals have multiple purposes; they should be a self-service support hub, a trust signal, a documentation database and a DevRel tool. There’s a developer journey of various steps, and each of these roles has its importance for different steps. Developer Experience (DX) is a combination of engagement, achievement and the right tools. There’s also DocX, the Documentation Experience, which can be considered in its own right.

Next up was Eva Casado de Amazua. She was employee #6 at Barcelona-based startup TypeForm, which has since grown to 180 staff, and she was a fundamental part of establishing a platform approach and a dedicated platform team. They call her “the woman of a thousand hats”. Developer users are beneficial multiplicators for TypeForm but, as Eva told from personal experience, a mindset for developers was difficult to establish in a company founded by designers. Internal hackathons not just for developers were helpful. The journey is still ongoing as it turned out to be more complex than expected. I loved the term “Peter Pan API” which she used for their first immature API that “acted like a teenager”.

Stella Crowhurst from WorldPay talked about consolidating APIs. WorldPay has grown a lot through M&A activities (mergers and acquisitions) and thus had a lot of separate developer products. They also realized how much they lack behind modern competitors like Stripe but “don’t want to be considered a bank”. To kick off the refactoring, the company brought all stakeholders together in multiple focus workshops. Then they changed their tooling and tried to establish Docs-as-Code and even Docs-in-Code, to let developers take part in the documentation. Stella showed off their API catalog and how they, while still having multiple different APIs, make it easy for developers to filter down to the APIs that are relevant for them through Amazon-like filters. Stella brought her colleague Nick on stage to explain their tech stack for documentation; in essence, they use Markdown files hosted on GitHub which are then rendered with a custom Angular-based application. They also define OpenAPI within code and even follow HATEOAS. He also showed a nice tool they build called DevBot, which is essentially a conversational interface into their API documentation.

In the last slot before lunch (one more was planned, but unfortunately Adeel Ali from APIMATIC had canceled) there was Karen Sawrey from Ukraine-based security company Cossack Labs. She was a returning speaker to API the Docs and talked about migrating documentation off of GitHub and into their own site. She learned the hard way that many tools for exporting from GitHub aren’t perfect and custom code is required. One of the hardest parts was making sure that all the links, relative and absolute, still work after migration. And even though they migrated their content out of GitHub, Karen stressed that GitHub wikis still have a role as a marketing tool to connect with the broader developer community and act as an entry point to documentation.

My own speaking slot was right after lunch. I had named my talk “To SDK or not to SDK?” and I talked about the advantages of providing SDKs, some strategies to approach SDKs and include community contributions. At the same time, I emphasized making sure that the raw API behind the SDK is still accessible to developers who can’t use the SDK, e.g., because they use a different language, or rather prefer not to.

Following me, there was Bridget Khursheed who talked about API security. She warned the community that APIs are now the primary target for attacks against other systems because they already give away a lot about the technical systems and they’re often well structured and allow a hacker to fill in the blanks. She gave a simple example of an error message in the Facebook API that, while indicating the fact that the access token used has no access, the route still exists and is probably accessible with another token, such as one extracted from the Facebook mobile app. Bridget reminded us to do audits and penetration testing on APIs regularly. It’s also useful to practice OPSEC, such as not using code and examples based on your own company internals.

Up next we had Ken Davies. He’s a technical writer responsible for release notes. They are probably often disregarded but very important because, in essence, release notes are a distilled version of the documentation. They need to communicate changes to different stakeholders, both internally and externally, and they can help break up silos. Writing about API changes in release notes is especially interesting, because it needs to be said what changed, why it did and how to use it, and this info should be clear. Ken ended up with the need to help developers understand the role of documentation and left us with a new acronym: RTFRN – read the ** release notes!

Next to last there was Taylor Barnett from Stoplight, an OpenAPI and developer portal service company. She talked about the role of OpenAPI and its potential to do more than just generate API documentation from the definition. She also debunked the idea that OpenAPI would remove the need for technical writers, saying that instead, it provides space to focus on “the good stuff”, such as writing tutorials. Mocking APIs with OpenAPI is also an opportunity for technical writers, who are closer to the end user than the developers who built the API, to test the API early and offer their informed opinion. She left by saying building better APIs means building API experiences.

And last of the day was Anthony Sansone from MongoDB who, just like Karen earlier, had also spoken in Amsterdam. Back then, he mentioned that their company is generating OpenAPI definitions from the code for their APIs. He followed up on this with a more technical talk about how they do it using Swagger-Core annotations in Java, with a few hints on the limitations and difficulties of the approach. In brief, he also mentioned how an MVC architecture works for APIs and how annotations are split between views and controllers. Anthony said that the output is not perfect and needs some customization and the entire approach also requires technical writers to become familiar with the development environment. He sees it as a transition to a specification-first strategy to be implemented later.

We’ve put some photos of the speakers on our Instagram profile.

The Unconference

Due to another canceled event session, the API the Docs organizers tried something new and added an unconference session at the end where participants could suggest topics and meet in smaller groups to discuss. The main discussions were about OpenAPI documentation tools beyond Swagger-UI and internal-facing developer portals. This is a format that I believe should be explored further at future events.

The Conclusion

The whole API economy is at a stage where more organizations than ever run developer programs either because regulation forces them to or, even better, if they are intrinsically motivated to innovate. Many of them have grasped the need to deliver good developer experience through proper API documentation and well-designed developer portals. Large organizations like WorldPay and banks are playing catch up with startups by updating their developer programs to the expectations that upstarts like Stripe have set. It’s an exciting time for everyone working with APIs!

And just like in Amsterdam before, I had a great day with the API the Docs community. The organizers did a great job in bringing this event to the French capital. The selection of talks was broad, and the quality was high. In some ways, the two conferences were very much alike, but I also felt a slightly distinct spirit and atmosphere that I can’t put into words, but this should not sound negative or judgemental in any way. I’m still looking forward to more.