Haufe API style guide

Purpose

Great RESTful APIs look like they were designed by a single team. This promotes API adoption, reduces friction, and enables clients to use them properly. To build APIs that meet this standard, and to answer many common questions encountered along the way of RESTful API development, the Haufe-Lexware CTO team has created this comprehensive set of guidelines. We have shared it with you to inspire additional discussion and refinement within and among your teams, and contribute our learnings and suggestions to the tech community at large.

Usage

The API style guide MUST be used when you create an API, refactor or extend an API, no exeptions. Existing APIs might be subject to adapt if there is business value in it.

It is the responsibility of the person implementing the API to apply the API Styleguide to a specific API and project!

Please follow the guidelines, but don't follow blindly!
You can break the rules by talking to us and providing justification.

The style guide is work in progress. We’d love your feedback – whether you agree, disagree, or have some additional practices and tips to add.

We encourage you to improve the style guide with modifications and extensions via the usual Fork/Pull Request dance. If your modification gets merged, it becomes part of the Styleguide. On the other hand if you don't bother, don't complain.

API Design Review Process

We are still at the beginning of our journey to an API driven company.

There will be pros and cons how to handle and apply the style guide to real projects. There are many things to learn and to share with another. Feel free to reach out and ask and share on the #apistrat channel on our Haufe RocketChat.

The API Design Review Process is mandatory for each new or refactored API at Haufe-Lexware.

Content

Most important chapters

Please read the bold chapters beow. These chapters describe the intent, mindset and process how we want to design an API.

Each section contains links to the chapters with more details.

Table of Content

The chapters are:

• Introduction
• General Guidlines
• API Design Principles
• API Design Process
• API Design Review Process
• REST Principles
• URI Components and Versioning
• HTTP Verbs
• Hypermedia and REST
• Resources
• Relationships and Sub-Resources
• Collection Resources
  • Resource naming
  • Get List of resources
  • Read Single Resource
  • Update Single Ressource
  • Update Partial Single Resource
  • Delete Single Resource
  • Create New Resource
  • Create New Resource - Consumer Supplied Identifier
• Filtering, sorting, field selection and paging
• Hypermedia Response Format
• Type Formatting
• Message Schema and Postels Law
• Security and Authentication
• Search
• Documentation
• Error handling
• HTTP Status Codes
• Caching
• Correlation-Id
• API Management
• FAQ
• Further Reading

Credits

For the creation of the style guide I took a lot of input from other authors and even copied whole passages.

I want to gratefully thank these authors and hope that I marked the relevant passages. My resources are listed under Further Reading. Special thanks goes to

S.Stedman and G. Laforge from Paypal
Brian Mulloy
Geert Jansen
Vinay Sahni
Michel Triana
Stefan Jauker

Another great inspiration were Zalando's Restful API Guidelines.