RESTful API

[rogerxu]

REST API Tutorial

microsoft/api-guidelines: Microsoft REST API Guidelines

aisuhua/restful-api-design-references: RESTful API 设计参考文献列表，可帮助你更加彻底的了解REST风格的接口设计。

A Beginner’s Guide to HTTP and REST

[rogerxu]

Best Practices

Best Practices for Designing a Pragmatic RESTful API | Vinay Sahni

10 Best Practices for Better RESTful API | Thinking Mobile

API Compatibility

API Versioning

All APIs MUST be versioned. Changes inside of a given API version MUST NOT lead to a compatibility break on the consumer side.

Whereas an API SHOULD keep the compatibility guarantee as long as possible, incompatible changes cannot be always avoided. In case of incompatible changes, the API owner MUST increase the API version to indicate the change.

Every API version MUST be represented as whole number (semantic versioning, like <major.minor.patch> MUST NOT be used). The version number increases sequentially in response to the need of introducing incompatible changes. This corresponds to the major part of a version notation in semantic versioning. Every API version MUST be part of the API URI. In the URI, the version MUST be encoded as a single decimal integer, which SHOULD be preceded by a small "v". The

Example:

https://api.domain.com/namespace-example/v1/users/123

API Lifecycle

API Features: Invalid vs. Unimplemented vs. Unknown

URI Formatting

Modeling of Resources

State Management

HTTP Verbs

HTTP Status Codes

Custom HTTP Headers

Error Response: Common Structure

Naming Conventions

Data Query Patterns

Data Conventions

Content Handling

JSON as a Content Type

Cache Handling

[rogerxu]

OpenAPI

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services.

Home - OpenAPI Initiative

OAI/OpenAPI-Specification: The OpenAPI Specification Repository

The Best APIs are Built with Swagger Tools | Swagger

Schema

JSON Schema Core

draft-wright-json-schema-00 - JSON Schema: A Media Type for Describing JSON Documents

Keywords for Applying Subschemas With Boolean Logic

allOf

anyOf

oneOf

not

Keywords for Applying Subschemas to Arrays

items

additionalItems

Keywords for Applying Subschemas to Objects

properties

patternProperties

additionalProperties

Dict:
  type: object
  additionalProperties:
    type: string
  example:
    foo: str1
    bar: str2

JSON Schema Validation

draft-wright-json-schema-validation-00 - JSON Schema Validation: A Vocabulary for Structural Validation of JSON

Validation for Any Instance Type

type

enum

Validation for Numeric Instances

multipleOf

maximum

exclusiveMaximum

minimum

exclusiveMinimum

Validation for Strings

maxLength

minLength

pattern

Validation for Arrays

maxItems

minItems

Validation for Objects

maxProperties

minProperties

required

Fixed Fields

nullable

discriminator

deprecated

format

4.4 Data Types - OpenAPI Specification

type	format	Comments
integer	int32	signed 32 bits
integer	int64	signed 64 bits (long)
number	float
number	double
string
string	byte	base64 encoded characters
string	binary	any sequence of octets
boolean
string	date
string	date-time
string	password	A hint to UIs to obscure input

Path Item Object

Operation Object

Parameter Object

Request Body Object

Response Object

Reusable Component

Inheritance

The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.

While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the discriminator field. When used, the discriminator will be the name of the property that decides which schema definition validates the structure of the model. As such, the discriminator field MUST be a required field.

[rogerxu]

API Naming Guidelines

Acronyms

• Avoid using acronyms in API names as much as possible.
• If you cannot avoid acronyms, use only well-known ones, such as XML, SQL, DB, or ID, or acronyms that are known in the context of this API.
• There is no standard or consensus on the capitalization of acronyms in the development community. The most commonly used rules of capitalization are as follows:
  • Two and three letters: capitalize everywhere except for the first word in lower camel case. For example: userID, getDBName, getURL, getSQLExpression, ioChannel.
  • Four and more letters: capitalize as a word. For example: HttpRequest, loadHtml, smtpServer.

A Unique Name for the API

• Use the singular word "API" to describe a whole set of functions. Incorrect: Custom Forms APIs Good: Custom Forms API
• Use capitalized words before "API". This is the preferred industry standard. Incorrect: transaction monitoring API Good: Transaction Monitoring API
• For simplicity, the name should not contain the language or the architecture style like Java or REST, but only reflect the purpose or functionality of the API. Incorrect: Supplier Data REST API Good: Supplier Data API
• Do not use verbs, prepositions, and abbreviations. Incorrect: Configuring Portal API Good: Portal Configuration API
• Avoid acronyms. Incorrect: DB Connection API Good: Data Access API

Note:

• If an API is released as a service, make sure the API name is different from the service name, to avoid confusion.
• Do not call an API a microservice. A microservice is a self-contained component of a system and application, which is meant to do only one thing. APIs and microservices are not the same, but can work together: A microservice uses an API to connect and communicate with the other parts of the system or with other microservices. The backend of an API can be deployed as a microservice on a system.

Common API Naming Mistakes

• Too long names: difficult to read, understand, and use Incorrect: recalculateNodePresentationLayoutObjects() Good: recalculateNodeLayouts()
• Ambiguous names: confusing Incorrect: getData() Good: getAddress()
• Plurals inside combined names: grammatically incorrect Incorrect: getRecordsCount() Good: getRecordCount()
• Ambiguous abbreviations: meaning is unclear and confusing Incorrect: ClientProviderAuth Good: ClientProviderAuthentication
• Product names: subject to change Incorrect: GitHubUserGroup Good: UserGroup
• Explaining implementation logic: does not concern the user Incorrect: updateIfModified() Good: update()
• Incorrect order of words: confusing Incorrect: maxRowCountEnable() Good: enableMaxRowCount()

[rogerxu]

Documentation Comments

Description

• In the summary sentence, omit clauses like "This class" or "This method". For a member that represents an action, start directly with a verb in the third-person form: adds, allocates, constructs, converts, deallocates, destroys, gets, provides, reads, removes, represents, returns, sets, saves and so on. For example:
  • Adds a new customer
  • Provides read and write access to employee data
  • Retrieves a Role object
• For a member that represents an object rather than an action, use a noun phrase. For example:
  • Base class for navigation
  • Alias of a backend system
• Avoid implementation details and dependencies unless they are important for usage.
• To avoid line wrapping, make sure each line of the description does not exceed 80 characters.
• In the output, the line breaks in a description are ignored, and it appears as a continuous text. To format descriptions, use HTML tags.
• To offset language keywords, API names, and code examples in a description, use the code tag.

/**
 * This is the summary sentence.
 * <p>
 * This is the detailed description. Note that you can have
 * multiple sentences in the detailed description.
 * </p>
 * 
 */

Tags

Generation tools support tags of the following types:

• Block tags that can be placed only in the tag section below the description. @tagname comment
• Inline tags that can be placed anywhere in documentation comments. {@tagname comment}
• HTML tags that can be used for the formatting of documentation comments. <tag></tag>

/**
 * Returns an Image object that can be painted on the screen.
 * The url parameter must specify an absolute {@link URL}.
 *
 * @param url An absolute URL of the image
 * @returns The image at the specified URL
 * @see Image
 */
public Image getImage(URL url);

• Keep a consistent order of tags across all your API reference. For example:

/**
 * @param
 * @return
 * @throws
 * @see
 * @since
 * @deprecated
 * @version
 */

• Begin a block tag comment with the upper case.
• Do not end a tag comment with a period if it is only one sentence or phrase.

[rogerxu]

OAuth 2.0

OAuth 2.0 — OAuth

OAuth 2.0 | Swagger

OAuth Grant Types

OAuth Grant Types

OAuth 2.0 的四种方式 - 阮一峰的网络日志

[rogerxu]

Best Practices

Errors

Error Handling - OData JSON Format Version 4.01

{
  "error": {
    "code": "INVALID_DATA", // required
    "message": "Wrong data in the payload.", // required
    "target": "payload",
    "details": [
      {
        "code": "INVALID_TYPE", // required
        "message": "Expected type array but found type object", // required
        "target": "name"
      }
    ]
  }
}

Validation

Swagger Validator

Structuring validation errors in REST APIs - Brainly Engineering - Medium

isa-group/oas-tools: NodeJS module to manage RESTful APIs defined with OpenAPI 3.0 Specs over express servers.

validationResult() · express-validator

express-ajv-swagger-validation - npm

Laminas API Tools

{
  "result": "error",
  "message": "Wrong data in the payload.",
  "details": [
    {
      "code": "INVALID_TYPE",
      "message": "Expected type array but found type object"
    }
  ]
}

Update Status

[rogerxu]

Swagger UI

Configuration

Swagger Documentation | Swagger

[rogerxu]

Better APIs

How to design better APIs (bluethl.net)

How to implement better APIs (bluethl.net)

1. Be consistent
2. Use ISO 8601 UTC dates
3. Make an exception for public endpoints
4. Provide a health check endpoint
5. Version the API
6. Accept API key authentication
7. Use reasonable HTTP status codes
8. Use reasonable HTTP methods
9. Use self-explanatory, simple names
10. Use standardized error responses
11. Return created resources upon POST
12. Prefer PATCH over PUT
13. Be as specific as possible
14. Use pagination
15. Allow expanding resources