microservice rest api - yibinericxia/documents GitHub Wiki

There are two popular API specifications: 1) OpenAPI Specification (OAS) also known as Swagger and 2) Restful API Modeling Language (RAML). The former has more users than the latter. API-first & Security-oriented design consists of the following important aspects:

1. Use /v1/ or /api/v1/ as a base url in the server url path in front of the resource endpoint easy to route via ingress/gateway and cache
2. Use version=v1 as a query parameter in the resource endpoint easy to default to
3. Use HTTP header
4. Use custom content negotiation

1. No verbs in the path. Use plurals and kebab-case in static path for resource collection. Use lowerCamel for path/query parameters for unique resource. For example, /static-paths/files?maxSize=123456&includeHidden=true.
2. Use path parameter for identifying specific resource and improving readability. Use query parameter for query function modification, such as filtering, sorting, paginating, etc.
3. Use HTTP methods for resource operations. Strictly follow Idempotent policy on GET, PUT, PATCH, DELETE. GET is read-only and cache-save without request body (the response body should be [] with 200 status code for resource collection). No request body for DELETE as well. Use 201 status code for POST which should return the response body with the format via Content-Type header.
4. Pay attention to the difference between POST (non-idempotent) and PUT (idempotent). See the link for details.

Data formats

• JSON
• XML
• RSS
• HTML
• PHP
• Text

Use ObjectMapper and XmlMapper for JSON and XML data

try {

// JSON to Java Object
InputStream inputStream = reponse.body().asInputStream();
ObjectMapper jsonMapper = new ObjectMapper();
jsonMapper.setSerializationInclusion(Include.NON_NULL);
MyObject myJavaObject = jsonMapper.readValue(inputStream, MyObject.class);
// JSON from Java Object
File file = File.createTempFile(...);
jsonMapper.writeValue(file, myObject);

// XML from Java Object
XmlMapper xmlMapper = new XmlMapper();
xmlMapper.setSerializationInclusion(Include.NON_EMPTY);
String xmlString = xmlMapper.writeValueAsString(myObject);
File file = new File(...);
xmlMapper.writeValue(file, myObject);
// XML to Java Object
MyObject myObject = xmlMapper.readValue(xmlString, MyObject.class);

} catch (...) {
...
}

Use Authorization via the following ways:

• Bearer Token
• OAuth
• JWT Bearer
• API Key

Web API should use POST instead of GET for sensitive data to avoid caching, storing in browser history and limitations on data

• Catalog APIs into clean categories
• Easy to comprehend and use including being consistent and logical
• Allow to search/sort and limit data by pagination
• Easy to debug with the status code
• Support multiple platforms including Cloud, Mobile, IoT

Use GitHub Actions to automatically generate JSON schemas and OpenAPI documentation, as well as test runs for code coverages and analysis metrics. See OpenAPI Automation and Flows for more details.

Spectral is a JSON/YAML linter which is often used to check rulesets for OpenAPI document, Postman collection, Kubernetes configuration, GitHub Action, etc.

Functional Testing Automation

• Query parameter validation
• Request body validation
• Output validation
• Feature coverage

Non-functional Testing

• Performance
• Usability
• Liability

Security Testing

• Authorization
• Authentication (RBAC)
• Please refer this for more details

Test using Postman

Test

• https://swagger.io/specification/
• https://editor-next.swagger.io/