In this API design course you learn to design HTTP APIs before the first line of code is written. It is aimed at developers and architects who already call APIs. You model resources and URIs, use HTTP methods and status codes appropriately, describe the interface with OpenAPI and define the error format, pagination, versioning and security requirements.
What you’ll take away.
- Derive resources and URIs from business entities and name them with nouns rather than verbs
- Use HTTP methods and status codes according to their meaning and identify idempotent operations
- Describe an API in OpenAPI first and implement it afterwards
- Define error responses, pagination and filtering consistently for all endpoints
- Version changes, keep them backward compatible and mark deprecated operations
Your training in detail
- Who is it for?
- Developers and software architects who already call HTTP APIs and now design or revise their own interfaces.
- Prerequisites
- Experience with HTTP requests and JSON, plus practice in any programming language. The examples are language-neutral.
- Format & planning
- Indicative range: 2 to 4 learning days, depending on prior experience, desired depth and practical scope. Duration is set only after discussing requirements.
Agenda: from understanding to application
Our independently developed agenda proposal. Focus areas, lab environment and scope are agreed before booking.
Resources and HTTP: modelling business entities as resources, URIs for collections and single items, GET, POST, PUT, PATCH and DELETE, idempotency and fitting status codes such as 201, 204, 400, 404 and 409.
Design-first with OpenAPI: the structure of an OpenAPI description with paths, operations, parameters, responses and reusable schemas. The description lives in source control as the single source of truth.
Consistent responses: a shared error format based on Problem Details (RFC 9457), separating client errors from server errors, pagination with limit and offset, filtering through query parameters and upper limits for result sets.
Versioning: versions through the URI, a query parameter, a header or the media type, telling backward-compatible changes from breaking ones, marking outdated operations with the deprecated field and planning their removal.
Security and verification: an overview of security schemes for OAuth 2.0 and OpenID Connect, the OWASP API Security Top 10 as a checklist, automated checks of the description in the CI pipeline and tests that compare the description with actual behaviour.
Suggested exercise: You design a small API for a given use case as an OpenAPI description, review it against a checklist and plan one backward-compatible and one breaking change.
Exams, licences & credentials
The course does not prepare for a vendor exam. Attending alone does not award a vendor certification.
Vendor references & review date
Sources checked on 2026-11-18. These sources describe the technology or external exam requirements. They do not imply a partnership with NextNowa.
- Microsoft Learn: Web API design best practices ↗
- Microsoft Learn: RESTful web API implementation best practices ↗
- Microsoft Learn: Handle errors in ASP.NET Core APIs ↗
- Microsoft Learn: Mitigate OWASP API security top 10 in Azure API Management ↗
- OpenAPI Initiative: OpenAPI Specification ↗
- OpenAPI Initiative: Best practices ↗
Your learning content
These objectives describe the training topic. The specific syllabus, duration, dates, trainer and price are agreed before booking.
As training for your team
You can request "Designing, documenting and versioning APIs" as training for your team only, live online. Content, examples and scope are agreed around your tasks. Date and total price are stated in the offer.
Frequently asked questions
Is this only about REST, or GraphQL as well?
The focus is on REST-style HTTP APIs and describing them with OpenAPI. GraphQL only appears here for comparison. It has its own course, “GraphQL: model, secure and test APIs”.
Which programming language do we use?
None in particular. The examples are language-neutral, because an OpenAPI description does not depend on a programming language. If your team uses a particular framework, mention it in your enquiry.
Who is the course for?
For developers and architects who already call HTTP APIs and now design, revise or publish their own for other teams. If you have never worked with HTTP requests and JSON, learn the basics of web development first.
Does Designing, documenting and versioning APIs include a certificate?
The course does not prepare for a vendor exam. Attending alone does not award a vendor certification.
