My journey in the API world really started about 3 years ago. During this time I was fortunate enough to learn good practices from several great mentors. Next month I will be co-hosting a tutorial at two major conferences, Oscon and Pycon. Teaching a development workflow, I believe to be the right way to develop REST APIs. My co-presenter is Dave Forgac. Dave and I are both passionate about good API design and practices. This is our way of contributing back to the API community that has been a great inspiration to us.
The idea to present on this subject surfaced in conversations I had with Dave about a year ago, as we were incorporating an API spec in our development workflow. We started this journey, presenting a talk by the name Fake it before you make it: Mocking your way to better HTTP APIs at PyOhio. The talk was well received and the feedback gave us great motivation.
Our journey continued and we extended the talk from PyOhio into a 3 hours hands-on tutorial. We were very excited when we got accepted to host this tutorial both at Oscon and Pycon. The tutorial is a natural evolution of the initial talk we gave. At PyOhio we presented a workflow that focused on building an API spec first, before working on the implementation. By writing the specification first you can present it to the consumer faster, and get feedback which will improve your design. You can also automatically generate tests, mock server and even some stub code. That can be more than half the work!
Building a tutorial has been a real challenge, as our goal is to attract people of different backgrounds to attend the sessions. It will be a hands- on experience. We want to challenge the students to solve the exercises on their own, but not to move so quickly that people feel left behind. Over the last month the content has been taking shape, and I feel we are on our way to striking that balance.
The tutorial will consist of two parts. In the first half, we present the OpenAPI Specification and by going through a series of lesson have the students write a full specification for a sample API. In the second half, we use the API spec the students prepared and go through a development life cycle where the student will generate tests, write implementation for the API, and even publish HTML documentation. We hope this experience will enable students to go back to their organization and use this workflow to improve their development lifecycle. Not only that, we also want to inspire experienced and junior developers alike to write better APIs using this approach.
As I said at the beginning of this post, I am very passionate about good API development practices. If you are attending Oscon or Pycon, I hope to see you in the audience. If you can’t make it to one of our sessions or aren’t able to make it to the conferences, feel free to reach out as I am always happy to talk APIs and share ideas.
I will write my next post after the conventions to share my experiences with you.
Ian Zelikman at OSCON
- Date: Tuesday, May 9, 2017
Location: Meeting Room 9
Dave Forgac and Ian Zelikman demonstrate how to use a contract-first approach to API development using the OpenAPI Specification (formerly called Swagger) and other open source tools. Dave and Ian walk you through defining a simple API specification, using it to generate documentation, a mock server, and stub code, and implementing a working API based on the specification.
- Date: Thursday, May 11, 2017
Location: Ballroom F
RESTful APIs are often designed and implemented before a client gets to see how they work, but once an API is made public, it can be hard to change. Dave Forgac and Ian Zelikman explain how to improve this process by explicitly designing the API contract and getting client feedback before implementation and outline processes and tools for building RESTful APIs with a design-first approach.