lcnbala / api-style-guide

Our resource pages are at

Haufe API style guide

Introduction

Purpose of this style guide is to gather a list of rules, best practices, resources and our way of creating REST APIs in Haufe Group. The style guide addresses API Designers, mostly developers and architects, who want to design an API. Intention is to ease the design process by providing helpful rules to create a succesful API that your customers will love. Please follow the guidelines but don't follow blindly! You can break the rules with justification. Please inform the CTO Office (mailto:[e-mail]) in this cases.

The style guide focuses on REST APIs cause this is the preferred way to expose APIs to our services.

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 Resources. Special thanks goes to

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

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.

Please contribute! 

The covered chapters are:

• API design best practices
• REST principles
• URI Components
• 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
• Response Format
• Type Formatting
• Message Schema and Postels Law
• Security and Authentication
• Search
• Documentation
• Error handling
• HTTP Status Codes
• Caching
• FAQ
• Further Resources