API Design

API Design - Versioning

• Spring blog - API Versioning in Spring (opens in a new tab)

  Spring Framework 7 built-in support for API versioning

API Design - Versioning - Version in URI

API Design - Versioning - Version in Accept Header

• Cons

  • DELETE method doesn't take Accept or Content-Type headers.

API Design - Versioning - Use custom HTTP Header

• Cons

  • Custom headers might be ignored by middleware

• GitHub REST API documentation (opens in a new tab)

• API Versioning Using Headers: A Clean and Flexible Approach (opens in a new tab)

API Design - Versioning - Resources

• 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 Versioning Strategies: Best Practices Guide (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

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)

API Implementation - Server

• OpenAPI

  • Swagger UI

    • Open local OpenAPI spec

      name: openapi
      services:
        swagger-ui:
          image: swaggerapi/swagger-ui
          container_name: swagger-ui
          environment:
            SWAGGER_JSON: /open-apis/openapi.json
          ports:
            - "5000:8080"
          volumes:
            - $PWD/target:/open-apis

  • 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

• Spring REST Docs (opens in a new tab)

  • Spring REST Docs WireMock Integration (opens in a new tab)

• 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)

API 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)

schemathesis (opens in a new tab)

Automatically generates thousands of test cases from your OpenAPI or GraphQL schema and finds edge cases that break your API.

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.

API Management

API Management - Traffic Control

API Management - Traffic Control - Rate Limiting

API Management - Traffic Control - Circuit Breaking

API Management - Traffic Control - Request/Response Transformation

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

API Management - API Gateway

API Management - 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)

API Management - Evolution

• API Evolution for REST/HTTP APIs (opens in a new tab)
• REST API Evolution (opens in a new tab)