In this workshop you will learn to design REST APIs that are secure, resilient and well-documented, following web standars, such as OpenAPI, HTTP and JSON-LD.

We’ll adopt a contract-first approach to ensure clarity and consistency, while also discussing when code-first tools like FastAPI can be safely used.

A methodological introduction will guide you in aligning business goals with technical implementation using the “API Canvas”.

Finally, we’ll explore strategies for maintaining consistency across APIs in multi-organization ecosystems, including:

• enforcing API guidelines for service management and security.
• aligning schema semantics through schema registries and linked data principles.

Agenda

• 10’ Goals and Setup
• 15’ Introducing OpenAPI, JSON Schema and service HTTP headers
• 15’ Contract-First or Code-First?
• 15’ API Canvas Design Metodology
• break
• 15’ Assisted API Design (with Spectral and https://italia.github.io/api-oas-checker/)
• 15’ Secure schema modeling
• 10’ Schema registries and semantics with JSON-LD
• 10’ Adding API Semantics (with JSON-LD and Schema Editor
• break
• 15’ API Semantics reprise
• 15’ The importance of service management
• 10’ Rate Limiting
• 10’ Caching
• 10’ Closing remarks

Preparation

The workshop requires:

• internet connection
• access online tools that we’ll use to design the API
• customizable python3 intepreter

Sources, docker-compose and further materials will be available on github.com before the date.