API Design

API Design - Versioning

• Versioning in API design: What it is, and deciding which version of versioning is right for you (opens in a new tab)
• API versioning best practices: When you need versioning and when you don't (opens in a new tab)
• Four REST API Versioning Strategies (opens in a new tab)
• REST Misconceptions Part 6 - Versioning and Hypermedia (opens in a new tab)

API Design - Relationship

• API links vs keys: Why you should use links, not keys, to represent relationships in APIs (opens in a new tab)
• Why your APIs should be entity-oriented (opens in a new tab)
• APIs 101: Everything you need to know about API design (opens in a new tab)
• gRPC vs REST: Understanding gRPC, OpenAPI and REST and when to use them in API design (opens in a new tab)
• Names vs identifiers in URLs: Which should you use in your API design? (opens in a new tab)
• Thoughts on REST APIs: Open API v. Hypermedia (opens in a new tab)

API Implementation

• Client

  • JDK HTTP Client (Java 11+)

    • OpenJDK - Java HTTP Client - Examples and Recipes (opens in a new tab)

    • OpenJDK - Introduction to the Java HTTP Client (opens in a new tab)

      • Methanol (opens in a new tab)

        An extension to provide missing features

  • Spring

    • Spring Cloud OpenFeign (opens in a new tab)

• OpenAPI

  • Swagger UI

    • Open local OpenAPI spec

      docker run --name swagger-ui -d -p 5000:8080 -v $PWD/target:/open-apis -e SWAGGER_JSON=/open-apis/openapi.json swaggerapi/swagger-ui

  • OpenAPI Generator (opens in a new tab)

    • Samples (opens in a new tab)

  • Springdoc (opens in a new tab)

    • API Docs in JSON format

      http://host/v3/api-docs/ (opens in a new tab)

    • API Docs in Swagger UI

      http://host/swagger-ui.html (opens in a new tab)

  • Edit and validate specs

    • Docker Hub - swaggerapi/swagger-editor (opens in a new tab)

      Can be used offline as a utility to edit and validate Swagger/OpenAPI specs

      • Swagger Blog - How to validate OpenAPI definitions in Swagger Editor using GitHub Actions (opens in a new tab)

  • OpenAPI.Tools (opens in a new tab)

    Curated list of OpenAPI projects

• Tooling

  • ReqRes API - Fake data CRUD API (opens in a new tab)

    • Use case: when you need fake data via HTTP (e.g. testing frontend UI)

    • ReqRes API - OpenAPI (opens in a new tab)

• Resources

  • Baeldung - Documenting a Spring REST API Using OpenAPI 3.0 (opens in a new tab)
  • Zalando RESTful API and Event Guidelines (opens in a new tab)

GraphQL

• Resources

  • GraphQL (opens in a new tab)
  • InfoQ - GraphQL Reference Guide: Building Flexible and Understandable APIs (opens in a new tab)

gRPC

API Management

Traffic Management

Rate Limiting

Circuit Breaking

Request/Response Transformation

• Unpacking API Management policies [Part 1]: How to transform or reformat your payload (opens in a new tab)

API Gateway

Kong

• Plugin

  • Kong Spec Expose (opens in a new tab)

    This plugin will expose the OpenAPI Spec (OAS), Swagger, or other specification of auth protected API services fronted by the Kong gateway.

  • OpenID Connect (opens in a new tab)

    OpenID Connect (1.0) plugin allows the integration with a 3rd party identity provider (IdP) in a standardized way. This plugin can be used to implement Kong as a (proxying) OAuth 2.0 resource server (RS) and/or as an OpenID Connect relying party (RP) between the client, and the upstream service.

  • Kong Plugin Hub (opens in a new tab)

• Admin

  • Postman Collection - Kong CE Admin API V2.0 (opens in a new tab)
  • Kong Gateway - Admin API (opens in a new tab)

Testing

Contract Testing

• Tools

  • swagger-request-validator (opens in a new tab)

• Resources

  • How to validate your Spring Boot implementation when choosing an API first approach? (opens in a new tab)
  • Contract-First Development Using RestAssured and OpenAPI (opens in a new tab)
  • Using Swagger Request Validator to Validate Spring Cloud Contracts (opens in a new tab)

Postman

• Resources

  • Postman Answers | Postman API Network (opens in a new tab)

Backing up collections on GitHub

• Postman Learning Center - Backing up collections on GitHub (opens in a new tab)

  • Requires a Personal Access Token, and if one token is used for all Collections backup, the token needs to be saved.
  • 1 Collection to 1 JSON file in a Git repo
  • Every save action in Postman to the Collection will trigger a Git commit and push to the remote repo.