The second endpoint – REST APIs

The code of the second endpoint that allows a client to create an entity looks like this:

app.MapPost(
    “/”,
    (CreateDto input) => new CreatedDto(
      Random.Shared.Next(int.MaxValue),
        input.Name
    )
);
public record class CreateDto(string Name);
public record class CreatedDto(int Id, string Name);

Here’s the API contract we can extract from the preceding code:

Contract segment	Value
HTTP Method	POST
URI	/
Input	An instance of the CreateDto class.
Output	An instance of the CreatedDto class.

Sending the following HTTP request (you can use the CreateEntity.http file) results in the output that follows:

POST / HTTP/1.1
Content-Type: application/json
Host: localhost:7000
Accept: application/json
Connection: keep-alive
Content-Length: 28

{
“name”: “Jane Doe”
}

The trimmed-down response is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 03 Jun 2023 17:59:25 GMT
Server: Kestrel
Alt-Svc: h3=”:7000″; ma=86400
Transfer-Encoding: chunked

{“id”:1624444431,”name”:”Jane Doe”}

As we can see from the preceding request, the client sent a serialized instance of the CreateDto class, set the name to Jane Doe, and received that same entity back but with a numeric id property (an instance of the CreatedDto class).The OpenAPI specs of our endpoint look like the following:

“/”: {
“post”: {
    “requestBody”: {
      “content”: {
        “application/json”: {
          “schema”: {
            “$ref”: “#/components/schemas/CreateDto”
          }
        }
      },
      “required”: true
    },
    “responses”: {
      “200”: {
        “description”: “Success”,
        “content”: {
          “application/json”: {
            “schema”: {
              “$ref”: “#/components/schemas/CreatedDto”
            }
          }
        }
      }
    }
}
}

The input and output schemas are:

“CreateDto”: {
“type”: “object”,
“properties”: {
    “name”: {
      “type”: “string”,
      “nullable”: true
    }
},
“additionalProperties”: false
},
“CreatedDto”: {
“type”: “object”,
“properties”: {
    “id”: {
      “type”: “integer”,
      “format”: “int32”
    },
    “name”: {
      “type”: “string”,
      “nullable”: true
    }
},
“additionalProperties”: false
},