Skip to main content

3 posts tagged with "Standard"

View All Tags

Commit Message Format

· One min read

Open in Notion

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

type as below:

  • feat: a new feature
  • fix: a bug fix
  • docs: changes to documentation
  • style: formatting, missing semi colons, etc; no code change
  • refactor: refactoring production code
  • test: adding tests, refactoring test; no production code change
  • chore: updating build tasks, package manager configs, etc; no production code change
  • ci: about ci
  • perf: performance change
  • WIP: work in progress

API Design Guide

· 2 min read

Open in Notion

Use RESTful service URLs​

Under REST principles, a URL identifies a resource. The following URL design patterns are considered REST best practices:

  • URLs should include nouns, not verbs.
  • Use plural nouns only for consistency (no singular nouns).
  • Use HTTP methods (HTTP/1.1) to operate on these resources:
  • Use HTTP response status codes to represent the outcome of operations on resources.

Response Http Status Code​

  • 200 OK
  • 400 Bad Request
  • 500 Internal Server Error

Other commonly seen codes include:

  • 201 Created
  • 204 No Content
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found

jQuery Ajax Request​

  • type: ‘GET’ —- dataType: ‘xml|json|script|text|html’ -> response http status code: 200 / 404
  • type: ‘POST’ —– dataType: ‘xml|json’ -> response http status code: 201 (created) / 405 (Method Not Allowed)
  • type: ‘PUT’ —— dataType: ‘xml|json’ -> response http status code: 200 / 404
  • type: ‘DELETE’ —— if return 204, dataType should not be ‘json’ -> response http status code: 200 / 404

Good RESTful URL examples​

List of magazines:

GET /api/v1/magazines.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Filtering and sorting are server-side operations on resources:

GET /api/v1/magazines.json?year=2011&amp;sort=desc HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

A single magazine in JSON format:

GET /api/v1/magazines/1234.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

All articles in (or belonging to) this magazine:

GET /api/v1/magazines/1234/articles.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

All articles in this magazine in XML format:

GET /api/v1/magazines/1234/articles.xml HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Specify query parameters in a comma separated list:

GET /api/v1/magazines/1234.json?fields=title,subtitle,date HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Add a new article to a particular magazine:

POST /api/v1/magazines/1234/articles.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript