Nowy Styl REST API Guidelines

Set of general rules and recommendations that have to be followed along the entire API lifecycle of any API regardless of its type. Please follow https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md

API First

Everyone MUST follow the API First principle.

The API first principle is an extension of contract-first principle. Therefore, a development of an API MUST always start with API design without any upfront coding activities.

API design (e.g., description, schema) is the master of truth, not the API implementation.

API implementation MUST always be compliant to particular API design which represents the contract between API, and it's consumer.

Contract

Approved API Design, represented by its API Description or schema, MUST represent the contract between API stakeholder, implementers, and consumers.

An update to the corresponding contract (API Design) MUST be implemented and approved before any change to an API MUST.

JSON

Any JSON-based message MUST conform to the following rules:

  1. All JSON field names MUST follow the Naming Conventions (camelCase, American English, etc.)

  2. Field names MUST be ASCII alpha num characters, underscore (_) or dollar sign ($)

  3. Boolean fields MUST NOT be of null value

  4. Fields with null value SHOULD be omitted

  5. Empty arrays and objects SHOULD NOT be null (use [] or {} instead)

  6. Array field names SHOULD be plural (e.g. "orders": [])