API Reference¶
The reference below is generated from the committed OpenAPI specification
(docs/openapi.yaml), which is produced from the server code by
template-go-api openapi. A CI drift-guard fails the build if the committed
spec falls out of sync with the code.
template-go-api dev¶
Todos¶
GET /v1/todos¶
List todos
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
apiKey |
header | string | N/A | No | API key supplied via the X-API-Key header or an Authorization: Bearer credential. |
cursor |
query | string | No | Opaque pagination cursor copied from a previous response's nextCursor; omit for the first page. | |
limit |
query | integer | 20 | No | Maximum number of todos to return per page. |
Responses
{
"$schema": "https://example.com/schemas/ListTodosOutputBody.json",
"nextCursor": "string",
"todos": [
{
"$schema": "https://example.com/schemas/TodoDTO.json",
"completedAt": "2022-04-13T15:42:05.901Z",
"createdAt": "2022-04-13T15:42:05.901Z",
"id": "string",
"status": "open",
"title": "string"
}
]
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ListTodosOutputBody.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"nextCursor": {
"description": "Opaque cursor for the next page; omitted when this is the last page.",
"type": "string"
},
"todos": {
"description": "The page of todos, oldest first.",
"items": {
"$ref": "#/components/schemas/TodoDTO"
},
"nullable": true,
"type": "array"
}
},
"required": [
"todos"
],
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
POST /v1/todos¶
Create a todo
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
apiKey |
header | string | N/A | No | API key supplied via the X-API-Key header or an Authorization: Bearer credential. |
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the request body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/CreateTodoInputBody.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"title": {
"description": "Human-readable title of the todo.",
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
"required": [
"title"
],
"type": "object"
}
Responses
{
"$schema": "https://example.com/schemas/TodoDTO.json",
"completedAt": "2022-04-13T15:42:05.901Z",
"createdAt": "2022-04-13T15:42:05.901Z",
"id": "string",
"status": "open",
"title": "string"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/TodoDTO.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"completedAt": {
"description": "When the todo was completed, if set.",
"format": "date-time",
"type": "string"
},
"createdAt": {
"description": "When the todo was created.",
"format": "date-time",
"type": "string"
},
"id": {
"description": "Unique identifier of the todo.",
"type": "string"
},
"status": {
"description": "Lifecycle state of the todo.",
"enum": [
"open",
"completed"
],
"type": "string"
},
"title": {
"description": "Human-readable title of the todo.",
"type": "string"
}
},
"required": [
"id",
"title",
"status",
"createdAt"
],
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
GET /v1/todos/{id}¶
Get a todo by id
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
apiKey |
header | string | N/A | No | API key supplied via the X-API-Key header or an Authorization: Bearer credential. |
id |
path | string | No | Unique identifier of the todo. |
Responses
{
"$schema": "https://example.com/schemas/TodoDTO.json",
"completedAt": "2022-04-13T15:42:05.901Z",
"createdAt": "2022-04-13T15:42:05.901Z",
"id": "string",
"status": "open",
"title": "string"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/TodoDTO.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"completedAt": {
"description": "When the todo was completed, if set.",
"format": "date-time",
"type": "string"
},
"createdAt": {
"description": "When the todo was created.",
"format": "date-time",
"type": "string"
},
"id": {
"description": "Unique identifier of the todo.",
"type": "string"
},
"status": {
"description": "Lifecycle state of the todo.",
"enum": [
"open",
"completed"
],
"type": "string"
},
"title": {
"description": "Human-readable title of the todo.",
"type": "string"
}
},
"required": [
"id",
"title",
"status",
"createdAt"
],
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
POST /v1/todos/{id}/complete¶
Mark a todo as completed
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
apiKey |
header | string | N/A | No | API key supplied via the X-API-Key header or an Authorization: Bearer credential. |
id |
path | string | No | Unique identifier of the todo. |
Responses
{
"$schema": "https://example.com/schemas/TodoDTO.json",
"completedAt": "2022-04-13T15:42:05.901Z",
"createdAt": "2022-04-13T15:42:05.901Z",
"id": "string",
"status": "open",
"title": "string"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/TodoDTO.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"completedAt": {
"description": "When the todo was completed, if set.",
"format": "date-time",
"type": "string"
},
"createdAt": {
"description": "When the todo was created.",
"format": "date-time",
"type": "string"
},
"id": {
"description": "Unique identifier of the todo.",
"type": "string"
},
"status": {
"description": "Lifecycle state of the todo.",
"enum": [
"open",
"completed"
],
"type": "string"
},
"title": {
"description": "Human-readable title of the todo.",
"type": "string"
}
},
"required": [
"id",
"title",
"status",
"createdAt"
],
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
{
"$schema": "https://example.com/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}
Schema of the response body
{
"additionalProperties": false,
"properties": {
"$schema": {
"description": "A URL to the JSON Schema for this object.",
"example": "https://example.com/schemas/ErrorModel.json",
"format": "uri",
"readOnly": true,
"type": "string"
},
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"example": "Property foo is required but is missing.",
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"nullable": true,
"type": "array"
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"example": "https://example.com/error-log/abc123",
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"example": 400,
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"example": "Bad Request",
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"example": "https://example.com/errors/example",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
Schemas¶
CreateTodoInputBody¶
| Name | Type | Description |
|---|---|---|
$schema |
string(uri) | A URL to the JSON Schema for this object. |
title |
string | Human-readable title of the todo. |
ErrorDetail¶
| Name | Type | Description |
|---|---|---|
location |
string | Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' |
message |
string | Error message text |
value |
The value at the given location |
ErrorModel¶
| Name | Type | Description |
|---|---|---|
$schema |
string(uri) | A URL to the JSON Schema for this object. |
detail |
string | A human-readable explanation specific to this occurrence of the problem. |
errors |
Array<ErrorDetail> | Optional list of individual error details |
instance |
string(uri) | A URI reference that identifies the specific occurrence of the problem. |
status |
integer(int64) | HTTP status code |
title |
string | A short, human-readable summary of the problem type. This value should not change between occurrences of the error. |
type |
string(uri) | A URI reference to human-readable documentation for the error. |
ListTodosOutputBody¶
| Name | Type | Description |
|---|---|---|
$schema |
string(uri) | A URL to the JSON Schema for this object. |
nextCursor |
string | Opaque cursor for the next page; omitted when this is the last page. |
todos |
Array<TodoDTO> | The page of todos, oldest first. |
TodoDTO¶
| Name | Type | Description |
|---|---|---|
$schema |
string(uri) | A URL to the JSON Schema for this object. |
completedAt |
string(date-time) | When the todo was completed, if set. |
createdAt |
string(date-time) | When the todo was created. |
id |
string | Unique identifier of the todo. |
status |
string | Lifecycle state of the todo. |
title |
string | Human-readable title of the todo. |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| apiKey | apiKey | API key supplied via the X-API-Key header or an Authorization: Bearer credential. |