reveal.js

Best Practices in REST API Documentation

Created by Łukasz Górnicki / @derberq
Working at SAP Hybris

Basics

Terminology

Docs Types

Overview
API Reference
Events
Details
Tutorials
Security
...and More

Specifications

RAML
OpenAPI/Swagger
API Blueprint

Why? What? How?

Style and Rules

Code formatting
Release notes
Code language
Voice and tone

What else?

Let us work it out together

REST API Documentation Guideliness: https://github.com/YaaS/REST_API_Documentation_Guidelines WaaS blog: https://github.com/YaaS/REST_API_Documentation_Guidelines/wiki

Technology

cause there is much more than just writing

Play with the API

Terminal vs User Interface

curl

							
								curl \
								-H "Authorization: Bearer {ACCESS_TOKEN}" \
								https://api.beta.yaas.io/hybris/document/v1/all/statistics \
								--verbose

Postman

Avoid the "not-invented-here" syndrome

Write API Specification

Automation

API Consoles

API Reference

The Future

GitHub is there already

Thanks!

This presentation: https://derberg.github.io/rest-api-docu-best-practices/ Static Site Generators: https://github.com/derberg/awesome-docs-with-static-site-generators
URI vs URL: https://danielmiessler.com/study/url-uri/
GitHub: derberg
Twitter: @derberq
reveal.js: https://github.com/hakimel/reveal.js