DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations

Trending

  • The SPACE Framework for Developer Productivity
  • Auditing Tools for Kubernetes
  • Real-Time Made Easy: An Introduction to SignalR
  • Insider Threats and Software Development: What You Should Know
  1. DZone
  2. Software Design and Architecture
  3. Integration
  4. 6 Tips for Documenting RESTful APIs

6 Tips for Documenting RESTful APIs

Need to document those RESTful APIs? These six tips will really help.

Tori Wieldt user avatar by
Tori Wieldt
·
Oct. 02, 15 · Analysis
Like (12)
Save
Tweet
Share
17.73K Views

Join the DZone community and get the full member experience.

Join For Free

If APIs are eating the world (as InformationWeek suggests), you can think of API documentation as recipes, a crucial part of making your API easy to understand and easy to use. Just as chefs rely on well-written recipes to create wonderful dishes, you need to create API documentation that is informative, succinct, and easy to read so other developers can cook up something wonderful using your APIs.

Andy Wilkinson, Spring IO Platform lead at cloud-native platform companyPivotal, provided great tips in his presentation “Documenting RESTful APIs” atSpringOne2GX in Washington, D.C., last month. Earned through hard-won experience, here are some tips Andy provided to help you create RESTful API documentation your users will love.  

1. Help Yourself When You Code

Good design decisions make it easier to document your APIs. Be consistent! If you can remain consistent in naming conventions and stick with existing standards for behavior, you’ll have to document an item only once … if at all! For example, for HTTP status codes: don’t bend meanings, don’t add new codes: “Don’t force users to understand your slightly eccentric view of the world.” Don’t go off the beaten path: 200 means OK. 404 means not found.

The same holds true for HTTP verbs: use POST to create, DELETE to delete. These are well-established conventions, violate them at your own risk. One exception: PUT and PATCH. The documentation for these is unclear (good luck with the RFC), and different apps have different interpretations of them. Some APIs make PUT and PATCH synonymous; just be clear on your particular usage. (You can find more info in this StackOverFlow discussion: What is the main difference between PATCH and PUT request?)

2. Document from a User’s Perspective

Remember that users come to your APIs with a mental model of the context you are working in. For example, if you are providing a payment processor, users are thinking in terms of charges, refunds, customers, and credit cards. So it makes sense to structure your documentation that way. For example, look at the Stripe API docs. They provide a nice introduction and then group APIs in a logical way. GitHub provides good example of well-organized RESTful API documentation, with groupings like Git Data, Pull Requests, Issues, and Users.

3. Don’t put URIs Front and Center

Making URIs the most obvious thing in your documentation requires users to figure out mapping between your logic and the HTTP client. Also, many users will hard code the URIs, which will break clients if you use hypermedia controls and then change them. This is the biggest drawback to the oft-used documenting tool Swagger. Swagger is popular because it provides a lot without much effort, but it generates docs that are URI-centric. For example, the vFabric Administration Server REST API documentation was inspired by Swagger. Because the URIs are so prominent and the structure is poor, this documentation may be accurate but it’s not terribly helpful. This is the example Andy provided because he helped create these docs, and learned some hard lessons from the experience.

4. Write in a Writing Tool

Write as much as possible in a format that’s designed for writing. “Writing documentation in annotations is horrendous,” Andy explained. Consider a tool such as ASCIIDoctor, a plain-text writing format for authoring documentation, notes, books, and also a publication toolchain. There is also a huge ecosystem around ASCIIDoctor, which includes lots of useful plugins.

5. Generate Examples Automatically and Combine Them With Your Explanations

Andy created the Spring REST docs project to help users get the information they need with a minimum of fuss. It combines handwritten documentation written with ASCIIDoctor and auto-generated snippets produced with Spring MVC Test. This combination hits the sweet spot between automation and manually generated information.

6. Plan for the Future

Look at the Richardson Maturity Model to determine how RESTful your APIs actually are. Your documentation tools can constrain you if your code is more RESTful (or you plan to make it more RESTful) than your tools allow. Don’t box yourself in. Do you plan to get to level 3 and use hypermedia? Then make sure your tools will support that.

As InfoWeek’s Thomas Claburn explains, “APIs make it possible for a few people with a great idea to offer a credible service worldwide with minimal effort and investment.” To make sure your great ideas get used by other developers, good API documentation should always be a part of your effort.

REST Web Protocols Documentation API

Published at DZone with permission of Tori Wieldt, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Trending

  • The SPACE Framework for Developer Productivity
  • Auditing Tools for Kubernetes
  • Real-Time Made Easy: An Introduction to SignalR
  • Insider Threats and Software Development: What You Should Know

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: