From 42ccbd02ab81d522c233ce386b0ec9642b1e6023 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Tue, 29 Apr 2025 13:53:13 -0600 Subject: [PATCH 1/6] API v endpoint v operation --- .../includes/api_endpoint_operation.md | 61 +++++++++++++++++++ aspnetcore/fundamentals/openapi/overview.md | 4 ++ 2 files changed, 65 insertions(+) create mode 100644 aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md diff --git a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md new file mode 100644 index 000000000000..761a86486e37 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md @@ -0,0 +1,61 @@ +## API v. Endpoint v. Operation + +The following section explains the differences between an API, an endpoint, and an operation in the context of ASP.NET Core and OpenAPI documentation: + +### API (Application Programming Interface) + +An API is a set of rules and protocols for building and interacting with software applications. It defines how different software components should communicate. In the context of ASP.NET Core, an API typically refers to a web service that exposes functionality over HTTP. + +In ASP.NET Core, an API is usually built using controllers or minimal APIs, which handle incoming HTTP requests and return responses. + +### API Operation + +An API operation represents a specific action or capability that an API provides. In ASP.NET Core, this corresponds to: + +* Controller action methods in MVC-style APIs +* Route handlers in Minimal APIs + +Each operation is defined by its HTTP method (`GET`, `POST`, `PUT`, etc.), parameters, and responses. + +### API Endpoint + +An API endpoint is the specific URL path where an operation can be accessed. It's the route pattern that clients target to invoke a particular operation. In ASP.NET Core: + +* For controller-based APIs, endpoints combine the route template with controller and action. +* For Minimal APIs, endpoints are explicitly defined with `app.MapGet()`, `app.MapPost()`, etc. + +### OpenAPI Documentation + +In the context of OpenAPI, the documentation describes the API as a whole, including all its endpoints and operations. OpenAPI provides a structured way to document APIs, making it easier for developers to understand how to interact with them. + +API Operations are the primary focus of OpenAPI documentation. The OpenAPI specification organizes documentation by operations, which are grouped by paths (endpoints). +Each operation is described with details such as parameters, request bodies, responses, and more. +This structured format allows tools to generate client libraries, server stubs, and interactive documentation automatically. + +In a OpenAPI document: + +* The entire document describes the API as a whole +* Each path item (like `/api/products/{id}`) represents an endpoint +* Under each path, the HTTP methods (`GET`, `POST`, `PUT`, etc.) define the operations +* Each operation contains details about parameters, request body, responses, etc. + +Example in OpenAPI JSON format: + +```JSON +json{ + "paths": { + "/api/products/{id}": { // This is the endpoint + "get": { // This is the operation + "summary": "Get a product by ID", + "parameters": [...], + "responses": {...} + }, + "put": { // Another operation on the same endpoint + "summary": "Update a product", + "parameters": [...], + "responses": {...} + } + } + } +} +``` diff --git a/aspnetcore/fundamentals/openapi/overview.md b/aspnetcore/fundamentals/openapi/overview.md index 96293769670d..ce74fe36cbfa 100644 --- a/aspnetcore/fundamentals/openapi/overview.md +++ b/aspnetcore/fundamentals/openapi/overview.md @@ -59,6 +59,10 @@ the output directory by setting the `OpenApiDocumentsDirectory` property. [!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)] +// ## API v. Endpoint v. Operation + +[!INCLUDE[](~/fundamentals/openapi/includes/api_endpoint_operation.md)] + ## ASP.NET Core OpenAPI source code on GitHub * [AddOpenApi](https://github.com/dotnet/aspnetcore/blob/main/src/OpenApi/src/Extensions/OpenApiServiceCollectionExtensions.cs) From 8cc19ed27705c36d34a7aa4b17267376ca4707c7 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Tue, 29 Apr 2025 14:37:21 -0600 Subject: [PATCH 2/6] API v endpoint v operation --- .../includes/api_endpoint_operation.md | 29 ++++++++++++++++--- aspnetcore/fundamentals/openapi/overview.md | 4 +-- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md index 761a86486e37..461acdc03703 100644 --- a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md +++ b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md @@ -1,10 +1,10 @@ -## API v. Endpoint v. Operation +## API v. API operation v. API endpoint -The following section explains the differences between an API, an endpoint, and an operation in the context of ASP.NET Core and OpenAPI documentation: +The following section explains the differences between an API, an API endpoint, and an API operation in the context of ASP.NET Core and OpenAPI documentation: ### API (Application Programming Interface) -An API is a set of rules and protocols for building and interacting with software applications. It defines how different software components should communicate. In the context of ASP.NET Core, an API typically refers to a web service that exposes functionality over HTTP. +An API is a set of rules and protocols for building and interacting with software applications. It defines how different software components should communicate. An API typically refers to a web service that exposes functionality over HTTP. In ASP.NET Core, an API is usually built using controllers or minimal APIs, which handle incoming HTTP requests and return responses. @@ -19,11 +19,22 @@ Each operation is defined by its HTTP method (`GET`, `POST`, `PUT`, etc.), param ### API Endpoint -An API endpoint is the specific URL path where an operation can be accessed. It's the route pattern that clients target to invoke a particular operation. In ASP.NET Core: +An API endpoint is a specific URL: + +* That represents a specific resource or functionality exposed by the API. +* Provides the exact address that a client needs to send an HTTP request to in order to interact with a particular API operation. + +An endpoint is a combination of the API's base URL and a specific path to the desired resource , along with the supported HTTP methods: * For controller-based APIs, endpoints combine the route template with controller and action. * For Minimal APIs, endpoints are explicitly defined with `app.MapGet()`, `app.MapPost()`, etc. +For example: + +* `GET /api/products` +* `POST /api/products` +* `PUT /api/products/{id}` + ### OpenAPI Documentation In the context of OpenAPI, the documentation describes the API as a whole, including all its endpoints and operations. OpenAPI provides a structured way to document APIs, making it easier for developers to understand how to interact with them. @@ -59,3 +70,13 @@ json{ } } ``` + +## API v. API operation v. API endpoint + +| Concept | API Operation | API Endpoint | +|-----------------|----------------------------------------------------|--------------------------------------------------| +| **Definition** | A logical description of an API action: method + path + behavior | The actual configured HTTP route that listens for requests | +| **Level** | Conceptual, what action can happen | Concrete, what URL and method are matched | +| **Tied to** | OpenAPI API design/specification | ASP.NET Core routing at runtime | +| **Describes** | What the API does e.g., "create product" | Where and how to call it, e.g., `POST https://localhost:7099/api/products`, `POST https://contoso.com/api/products` | +| **In ASP.NET Core** | Controller actions or Minimal API methods, before routing resolves | Endpoint objects resolved at runtime | diff --git a/aspnetcore/fundamentals/openapi/overview.md b/aspnetcore/fundamentals/openapi/overview.md index ce74fe36cbfa..ef897a7ccdec 100644 --- a/aspnetcore/fundamentals/openapi/overview.md +++ b/aspnetcore/fundamentals/openapi/overview.md @@ -59,8 +59,8 @@ the output directory by setting the `OpenApiDocumentsDirectory` property. [!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)] -// ## API v. Endpoint v. Operation - + [!INCLUDE[](~/fundamentals/openapi/includes/api_endpoint_operation.md)] ## ASP.NET Core OpenAPI source code on GitHub From 4251699d7124dbd8e52e3a21372721639d95983b Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Tue, 29 Apr 2025 16:24:23 -0600 Subject: [PATCH 3/6] API v endpoint v operation --- .../openapi/includes/api_endpoint_operation.md | 10 ++++------ aspnetcore/fundamentals/openapi/overview.md | 3 +-- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md index 461acdc03703..431cd40c91bb 100644 --- a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md +++ b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md @@ -1,6 +1,6 @@ ## API v. API operation v. API endpoint -The following section explains the differences between an API, an API endpoint, and an API operation in the context of ASP.NET Core and OpenAPI documentation: +The following sections explain the differences between an API, an API endpoint, and an API operation in the context of ASP.NET Core and OpenAPI documentation. ### API (Application Programming Interface) @@ -24,7 +24,7 @@ An API endpoint is a specific URL: * That represents a specific resource or functionality exposed by the API. * Provides the exact address that a client needs to send an HTTP request to in order to interact with a particular API operation. -An endpoint is a combination of the API's base URL and a specific path to the desired resource , along with the supported HTTP methods: +An endpoint is a combination of the API's base URL and a specific path to the desired resource, along with the supported HTTP methods: * For controller-based APIs, endpoints combine the route template with controller and action. * For Minimal APIs, endpoints are explicitly defined with `app.MapGet()`, `app.MapPost()`, etc. @@ -39,9 +39,7 @@ For example: In the context of OpenAPI, the documentation describes the API as a whole, including all its endpoints and operations. OpenAPI provides a structured way to document APIs, making it easier for developers to understand how to interact with them. -API Operations are the primary focus of OpenAPI documentation. The OpenAPI specification organizes documentation by operations, which are grouped by paths (endpoints). -Each operation is described with details such as parameters, request bodies, responses, and more. -This structured format allows tools to generate client libraries, server stubs, and interactive documentation automatically. +API Operations are the primary focus of OpenAPI documentation. The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) organizes documentation by operations, which are grouped by paths (endpoints). Each operation is described with details such as parameters, request bodies, responses, and more. This structured format allows tools to generate client libraries, server stubs, and interactive documentation automatically. In a OpenAPI document: @@ -78,5 +76,5 @@ json{ | **Definition** | A logical description of an API action: method + path + behavior | The actual configured HTTP route that listens for requests | | **Level** | Conceptual, what action can happen | Concrete, what URL and method are matched | | **Tied to** | OpenAPI API design/specification | ASP.NET Core routing at runtime | -| **Describes** | What the API does e.g., "create product" | Where and how to call it, e.g., `POST https://localhost:7099/api/products`, `POST https://contoso.com/api/products` | +| **Describes** | What the API does for example, "create product" | Where and how to call it, for example, `POST https://localhost:7099/api/products`, `POST https://contoso.com/api/products` | | **In ASP.NET Core** | Controller actions or Minimal API methods, before routing resolves | Endpoint objects resolved at runtime | diff --git a/aspnetcore/fundamentals/openapi/overview.md b/aspnetcore/fundamentals/openapi/overview.md index ef897a7ccdec..c937e70e3e75 100644 --- a/aspnetcore/fundamentals/openapi/overview.md +++ b/aspnetcore/fundamentals/openapi/overview.md @@ -59,8 +59,7 @@ the output directory by setting the `OpenApiDocumentsDirectory` property. [!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)] - + [!INCLUDE[](~/fundamentals/openapi/includes/api_endpoint_operation.md)] ## ASP.NET Core OpenAPI source code on GitHub From 9bfdb45e4d0730f3503c11d8964161f7bbbb2cbb Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 30 Apr 2025 13:41:13 -0600 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Mike Kistler Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../fundamentals/openapi/includes/api_endpoint_operation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md index 431cd40c91bb..0c902a0c2b0e 100644 --- a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md +++ b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md @@ -15,7 +15,7 @@ An API operation represents a specific action or capability that an API provides * Controller action methods in MVC-style APIs * Route handlers in Minimal APIs -Each operation is defined by its HTTP method (`GET`, `POST`, `PUT`, etc.), parameters, and responses. +Each operation is defined by its HTTP method (`GET`, `POST`, `PUT`, etc.), path, parameters, and responses. ### API Endpoint @@ -41,7 +41,7 @@ In the context of OpenAPI, the documentation describes the API as a whole, inclu API Operations are the primary focus of OpenAPI documentation. The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) organizes documentation by operations, which are grouped by paths (endpoints). Each operation is described with details such as parameters, request bodies, responses, and more. This structured format allows tools to generate client libraries, server stubs, and interactive documentation automatically. -In a OpenAPI document: +In an OpenAPI document: * The entire document describes the API as a whole * Each path item (like `/api/products/{id}`) represents an endpoint From 82915c324285edcaf2ff898ffa2e2f6444d8b3a9 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 30 Apr 2025 14:01:51 -0600 Subject: [PATCH 5/6] react to feedback --- .../fundamentals/openapi/includes/api_endpoint_operation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md index 0c902a0c2b0e..cf52f992593a 100644 --- a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md +++ b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md @@ -69,7 +69,9 @@ json{ } ``` -## API v. API operation v. API endpoint +## API, API operation, and API endpoint comparison + +The following table summarizes the differences between an API, an API operation, and an API endpoint: | Concept | API Operation | API Endpoint | |-----------------|----------------------------------------------------|--------------------------------------------------| From c33acbb1ee149a859cd46f092b15a9e5420f3434 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 30 Apr 2025 14:44:58 -0600 Subject: [PATCH 6/6] react to feedback --- .../openapi/includes/api_endpoint_operation.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md index cf52f992593a..7ac41b75855f 100644 --- a/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md +++ b/aspnetcore/fundamentals/openapi/includes/api_endpoint_operation.md @@ -4,10 +4,14 @@ The following sections explain the differences between an API, an API endpoint, ### API (Application Programming Interface) -An API is a set of rules and protocols for building and interacting with software applications. It defines how different software components should communicate. An API typically refers to a web service that exposes functionality over HTTP. +An API is a set of rules and protocols for building and interacting with software applications. It defines how different software components should communicate. In general web development, "API" typically refers to a web service that exposes functionality over HTTP. In ASP.NET Core, an API is usually built using controllers or minimal APIs, which handle incoming HTTP requests and return responses. +ASP.NET Core's internal naming conventions sometimes use "API" differently. For instance, in [API Explorer](/dotnet/api/microsoft.aspnetcore.mvc.apiexplorer), an "ApiDescription" actually represents an [API Operation](#api-operation) rather than the full API service. This distinction reflects internal naming conventions and sometimes differ from the broader definition used here. + +See [Introduction to the ApiExplorer in ASP.NET Core](https://andrewlock.net/introduction-to-the-apiexplorer-in-asp-net-core/) for more information on API Explorer. + ### API Operation An API operation represents a specific action or capability that an API provides. In ASP.NET Core, this corresponds to: @@ -29,11 +33,15 @@ An endpoint is a combination of the API's base URL and a specific path to the de * For controller-based APIs, endpoints combine the route template with controller and action. * For Minimal APIs, endpoints are explicitly defined with `app.MapGet()`, `app.MapPost()`, etc. -For example: +For example, the `api/products/{id}` endpoint that supports the following operations: -* `GET /api/products` -* `POST /api/products` +* `GET /api/products/{id}` * `PUT /api/products/{id}` +* `PATCH /api/products/{id}` +* `Delete /api/products/{id}` +* `HEAD /api/products/{id}` + +Endpoints often include query parameters, for example, `GET /api/products?category=electronics&sort=price` ### OpenAPI Documentation