Restclient and org-mode provide a superior alternative to separate tools
for documenting and testing RESTful APIs like Confluence and Postman. Restclient and org-mode integrate the functionality provided by separate documentation and testing tools into a single file that is easily
maintained and shared. As the document provides utility through interaction with the APIs it documents, there is an incentive for developers to prevent the prose and code it contains from drifting from the API implementation. This helps prevent the common problem of out of date API documentation that most engineering organizations suffer from. There are many additional benefits provided by restclient and org-mode that are not matched by any single tool. As the document is stored as plain text it can be read and understood outside Emacs on any computer. It can also be exported to multiple different formats, such as various markdown dialects, pdf, and html to be read and distributed. During the export process, sample responses from the APIs can be captured and exported automatically to provide accurate examples of what APIs return. Furthermore, because the user can execute many programming languages from within an org-mode file, it is possible to script custom logic not easily captured by other tools like Postman. The output of code blocks can be fed into subsequent code blocks to support modeling complex interactions with your APIs. Through
org-mode's tangling capability, you can export scripts that can be shared
with other stakeholders to replicate bugs and export data from APIs. It can be easily shared and worked on between engineers as all standard version control practices they are familiar with, such as branching, pull requests, etc., can be applied. Restclient and org-mode allows the user to integrate additional functionality into a ubiquitous tool (Emacs), and leverage all the power it has, rather than installing additional specialized tools on their system.
About the presenter:
Mack is currently a Back End Software Engineer at Turo, a peer to peer
carsharing company. He has a strong background in server side Java and
Kotlin. He enjoys dabbling with more esoteric languages like Clojure, and of course Emacs Lisp. He did his undergraduate degree in Edmonton, Alberta, Canada and has been working in the Bay Area for a little over two years. He currently doesn't use Emacs for work related programming, but he uses it for pretty much everything else.