Skip to content

Latest commit

 

History

History
175 lines (136 loc) · 11 KB

CONTRIBUTING.md

File metadata and controls

175 lines (136 loc) · 11 KB
Raw

Contributing to the Rebilly API definitions

👍🎉 Welcome! And thanks for taking the time to contribute! 🎉👍

Important note: we are designing in public (this repository is open for the world to see and contribute if they want). Do not post any confidential information in this repository (whether as a commit or a comment on a PR). See Rebilly security policies for more information about data classification.

Design APIs

Rebilly follows a design-first approach to APIs.

  • Use OpenAPI 3.0 to describe APIs according to below.
  • Use GitHub flow (create a branch and open a pull request for any change).
  • Check your work with Redocly CLI which runs lint and bundle commands controlled through the redocly.yaml configuration file when a pull request is opened (you will see the green checks or red x marks).
  • In terms of sequence, merge the API definitions before merging and releasing software to production.

To get started:

  • Set up your environment.
  • Read the remainder of this page to understand how we design APIs and write API definitions.

API description writing guidance

For guidance on how to write API descriptions when contributing to Rebilly APIs, see Writing style.

API style guide

Rebilly uses the following lint rules:

  • The Redocly recommended configuration denoted as "recommended"
  • Additional available Redocly rules denoted as "Redocly additional rules"
  • Custom rules denoted as "custom rules".

General

Info

Operations

Parameters

Paths

Requests, Responses, and Schemas

Servers

Tags

Writing style

Maintenance

Set up lint rules to enforce any design rules to keep this list to a minimum (and remove from this list as rules are enabled to automate these checks).

Schemas

  • The schema filename should be singular and start with an uppercase letter (Customer.yaml).
  • Always use US-English.
  • Define all properties explicitly (whenever possible).
  • List required properties.
  • Mark properties read or write only when appropriate.
  • Re-use schemas by reference objects ($ref). Some commonly used include:
    • ResourceId
    • CreatedTime
    • UpdatedTime
  • Most APIs have a _links property (with at least "self" link).
  • If a resource has nested objects, consider separating them with the reference objects ($ref) if they have potential for reuse.
  • You may organize schemas into sub-folders when appropriate.

Operations

  • Follow path conventions
  • Use appropriate HTTP methods.
    • POST to insert a new resource.
    • PUT to create with specified ID or replace existing Resource (must return 200 for updated and 201 for created).
    • GET to get a resource or a collection.
    • DELETE to delete a resource.
  • Response must contain http header Location of the newly created resource; if the status is 201, the Location header must exist.

Collections

  • Add "#/parameters/collectionLimit" and "#/parameters/collectionOffset" to Resource collection, if pagination is needed.
  • Add "#/parameters/collectionFields" to Resource collection to allow return only specified fields.
  • Add "#/parameters/collectionExpand" to Resource collection if Resource contains embedded resources.
  • Add "#/parameters/collectionQuery" to Resource collection if Resource support search by ‘?q=’ param.
  • Add "#/parameters/collectionFilter" to Resource collection if Resource support search by ‘?filter=’ param.
  • Add "#/parameters/collectionCriteria" to Resource collection if Resource support search by ‘?criteria=’ param.
  • Add "#/parameters/collectionSort" to Resource collection if Resource support sorting.
    • Define all sortable properties.

Helpful resources