Abstract
For a REST API we can produce an executable version of the documentation and allow users to interact with a system through its own documentation. In this sense, the documentation wouldn’t be a passive dust collector artifact (if stored in a printed form), but a handy UI to communicate with software.
This is a preview of subscription content, log in via an institution.
Buying options
Tax calculation will be finalised at checkout
Purchases are for personal use only
Learn about institutional subscriptionsNotes
- 1.
There are even IDEs (for example, the Restlet Studio) to help you produce the REST API specification in a generic fashion (without a need to prematurely stick to the concrete documentation system, like, Swagger, RAML, etc.). However, such tools hit their limits quite early, as we will showcase in this chapter.
- 2.
As this is a static file, without a chance to negotiate content, then it is okay to have a file extension inside the URL.
- 3.
Apiary is an excellent API specification framework with good support for testing.
- 4.
Something that is nicely illustrated at http://xkcd.com/1481/ .
- 5.
You might want to refactor the problem report entity and rename reportNumber to reportId. You might also want to add a timestamp when the error has ensued. Don’t forget to update the API documentation after these changes.
Author information
Authors and Affiliations
Rights and permissions
Copyright information
© 2016 Ervin Varga
About this chapter
Cite this chapter
Varga, E. (2016). Documenting REST APIs. In: Creating Maintainable APIs. Apress, Berkeley, CA. https://doi.org/10.1007/978-1-4842-2196-9_9
Download citation
DOI: https://doi.org/10.1007/978-1-4842-2196-9_9
Published:
Publisher Name: Apress, Berkeley, CA
Print ISBN: 978-1-4842-2195-2
Online ISBN: 978-1-4842-2196-9
eBook Packages: Professional and Applied ComputingProfessional and Applied Computing (R0)Apress Access Books