Functional API Design Guides

https://endpoints4s.github.io
Admin
This project provides a collection of guides and documentation on functional API design and...
Tokens:1,766,013
Snippets:20,344
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Server Startup Example

Source: https://endpoints4s.github.io/play

Provides an example of how to start an HTTP server using `NettyServer.fromRouterWithComponents` and integrating custom routes.

```APIDOC
## Server Startup Example

### Description
This example demonstrates the JVM entry point for starting an HTTP server using `NettyServer.fromRouterWithComponents`. It shows how to integrate custom routers, including those generated by `endpoints4s`.

### Example
```scala
import endpoints4s.play.server.{PlayComponents, ServerConfig}
import play.core.server.NettyServer

object Main {
  // JVM entry point that starts the HTTP server
  def main(args: Array[String]): Unit = {
    val playConfig = ServerConfig(port = sys.props.get("http.port").map(_.toInt).orElse(Some(9000)))
    NettyServer.fromRouterWithComponents(playConfig) { components =>
      val playComponents = PlayComponents.fromBuiltInComponents(components)
      // Assuming CounterServer and DocumentationServer are defined elsewhere and provide routes
      // new CounterServer(playComponents).routes.orElse(new DocumentationServer(playComponents).routes)
      ??? // Placeholder for actual routes
    }
    ()
  }
}
```
```

--------------------------------

### Start a Play Framework HTTP Server

Source: https://endpoints4s.github.io/play/index.html

Example of starting a Play Framework HTTP server using NettyServer and integrating custom routes.

```scala
object Main {
  // JVM entry point that starts the HTTP server
  def main(args: Array[String]): Unit = {
    val playConfig = ServerConfig(port = sys.props.get("http.port").map(_.toInt).orElse(Some(9000)))
    NettyServer.fromRouterWithComponents(playConfig) { components =>
      val playComponents = PlayComponents.fromBuiltInComponents(components)
      new CounterServer(playComponents).routes
        .orElse(new DocumentationServer(playComponents).routes)
    }
    ()
  }
}
```

--------------------------------

### Define a basic HTTP endpoint

Source: https://endpoints4s.github.io/algebras/endpoints.html

Use the `endpoint` constructor to define an HTTP endpoint with a specific verb, URL path, and response type. This example creates a GET endpoint at '/some-resource' that returns plain text.

```scala
val someResource: Endpoint[Unit, String] = \
  endpoint(get(path / "some-resource"), ok(textResponse))
```

--------------------------------

### Add Example to JSON Schema

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonEntitiesFromSchemas.html

Includes an example value within the given JSON schema.

```APIDOC
## withExampleJsonSchema[A](schema: JsonSchema[A], example: A): JsonSchema[A]

### Description
Include an example value within the given JSON schema.

### Method
Abstract method definition.

### Endpoint
N/A (Schema modification operation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None (This is a schema modification, not an API call)

### Response
#### Success Response (N/A)
Returns the modified `JsonSchema[A]` with the included example.

#### Response Example
None (This is a schema modification, not an API call)
```

--------------------------------

### Add Example to Schema

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonSchemas%24RecordOps.html

Includes an example of a value in this schema. Primarily used for documentation purposes.

```APIDOC
## withExample

### Description
Include an example of value in this schema. Encoder and decoder interpreters ignore this value, while documentation interpreters can show this example value.

### Method
`withExample(example: A): Record[A]`

### Parameters
#### Path Parameters
- **example** (A) - Required - Example value to attach to the schema
```

--------------------------------

### Include Example in JSON Schema

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonSchemas.html

Includes an example value within the given JSON schema.

```APIDOC
## withExampleJsonSchema[A](schema: JsonSchema[A], example: A): JsonSchema[A]

### Description
Include an example value within the given JSON schema.

### Method
Abstract method definition.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **JsonSchema[A]** - The JSON schema with an included example.

#### Response Example
None
```

--------------------------------

### Add Example to Tagged Schema

Source: https://endpoints4s.github.io/api/endpoints4s/pekkohttp/server/JsonEntitiesFromSchemas.html

Includes an example value within a tagged JSON schema.

```APIDOC
## withExampleTagged

### Description
Include an example value within the given tagged JSON schema.

### Method
N/A (Helper function)

### Parameters
- **tagged** (Tagged[A]) - The tagged schema to add an example to.
- **example** (A) - The example value.
```

--------------------------------

### withExample

Source: https://endpoints4s.github.io/api/endpoints4s/openapi/model/Schema%24%24AllOf.html

Sets an example value for the schema.

```APIDOC
## withExample

### Description
Sets an example value for the schema.

### Method
`withExample(example: Option[Value]): AllOf`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **AllOf** (AllOf) - The modified AllOf schema object.
```

--------------------------------

### Endpoints Trait Example

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/Endpoints.html

An example demonstrating how to describe a simple HTTP endpoint using the `endpoint` function. This specific example defines a GET request to the path '/foo' with no response entity.

```APIDOC
## GET /foo

### Description
Describes an HTTP endpoint whose:
 - request uses verb “GET”,
 - URL is made of path “/foo”,
 - response has no entity

### Method
GET

### Endpoint
/foo

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
No entity

#### Response Example
```json
{}
```
```

--------------------------------

### Example Usage of JsonEntities

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonEntities.html

This example demonstrates how to define an HTTP endpoint that uses JSON for its response. It describes an endpoint that responds to a GET request at '/user/{id}' with a JSON payload representing a User object.

```APIDOC
## GET /user/{id}

### Description
Describes an HTTP endpoint that responds to a GET request at '/user/{id}' with a JSON payload representing a User object.

### Method
GET

### Endpoint
/user/{id}

### Parameters
#### Path Parameters
- **id** (UUID) - Required - The ID of the user.

### Response
#### Success Response (200)
- **User** (User) - The user object in JSON format.
```

--------------------------------

### withExample

Source: https://endpoints4s.github.io/api/endpoints4s/openapi/model/Schema%24%24OneOf.html

Sets an optional example value for the OneOf schema. This can be used to illustrate a typical value that conforms to the schema.

```APIDOC
## withExample

### Description
Sets an optional example value for the OneOf schema. This can be used to illustrate a typical value that conforms to the schema.

### Method
N/A (Method Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### HTTP Operations

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/circe/JsonEntitiesFromCodecs.html

Examples of common HTTP operations using endpoints4s, including GET and DELETE requests.

```APIDOC
## GET request

### Description
Helper method to perform GET request

### Method
GET

### Endpoint
[Full endpoint path with any path parameters]

### Parameters
#### Path Parameters
- **UrlP** (type) - Description

#### Query Parameters
- **HeadersP** (type) - Description

## DELETE request

### Description
Helper method to perform DELETE request

### Method
DELETE

### Endpoint
[Full endpoint path with any path parameters]

### Parameters
#### Path Parameters
- **UrlP** (type) - Description

#### Query Parameters
- **HeadersP** (type) - Description
```

--------------------------------

### Example: Adding Basic Auth Headers

Source: https://endpoints4s.github.io/api/endpoints4s/fetch/JsonEntitiesFromSchemas.html

Demonstrates how to map an endpoint's request to include basic authentication headers.

```scala
val myEndpoint: Endpoint[Input, Output] = ???
val basicAuthHeaders: RequestHeaders[Credentials] = ???

val endpointWithAuth = myEndpoint.mapRequest(basicAuthHeaders.add(_))
```

--------------------------------

### withExample

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonSchemas%24JsonSchemaDocumentationOps.html

Adds an example value to the schema. This example is ignored by encoder and decoder interpreters but can be shown by documentation interpreters.

```APIDOC
## withExample

### Description
Include an example of a value in this schema. Encoder and decoder interpreters ignore this value, but documentation interpreters can show it.

### Method
abstract def withExample(example: A): Self

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **Self** (type of Self) - The modified schema with the example.

### Response Example
```json
{
  "example": "Modified schema object with example value"
}
```
```

--------------------------------

### Example Endpoint Description

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/index.html

Describes an HTTP endpoint with a GET verb, a path of '/foo', and no response entity.

```APIDOC
## GET /foo

### Description
Describes an HTTP endpoint whose: - request uses verb “GET”, - URL is made of path “/foo”, - response has no entity

### Method
GET

### Endpoint
/foo

### Response
#### Success Response (200)
- (empty)

### Response Example
(empty)
```

--------------------------------

### Example URL Path Construction

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/Urls%24PathOps.html

Demonstrates how to construct a URL path with segments and query parameters using PathOps. This example defines a path starting with 'articles', followed by a string segment, and then a query string with a mandatory 'lang' parameter and an optional 'page' parameter.

```scala
/**
  * Describes an URL starting with a segment containing “articles”, followed
  * by another `String` segment, and a query string containing
  * a mandatory `Lang` parameter named “lang”, and an
  * optional `Int` parameter named “page”.
  *
  * Examples of matching URLs:
  *
  * - /articles/kitchen?lang=fr
  * - /articles/garden?lang=en&page=2
  */
val example = path / "articles" / segment[String]() /? (qs[Lang]("lang") & qs[Option[Int]]("page"))
```

--------------------------------

### Basic Authentication Example

Source: https://endpoints4s.github.io/api/endpoints4s/sttp/client/BasicAuthentication.html

Demonstrates how to use basic authentication with sttp client. This snippet shows how to create a request with username and password.

```scala
import sttp.client._

val request = basicRequest.auth.basic("user", "password")
```

--------------------------------

### withExample

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonSchemas%24TaggedOps.html

Includes an example value for the schema. This example is ignored by encoder and decoder interpreters but can be displayed by documentation interpreters.

```APIDOC
## withExample

### Description
Includes an example of a value that conforms to this schema. This example is intended for documentation and is not used during encoding or decoding.

### Method

```scala
def withExample(example: A): Tagged[A]
```

### Parameters

* **example** (A) - Required - An example value conforming to the schema.

### Response

* **Tagged[A]** - The schema with the added example value.

### Request Example

```scala
val schemaWithExample = myTaggedSchema.withExample(123)
```
```

--------------------------------

### Define a basic HTTP endpoint

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/Endpoints.html

Describes an HTTP endpoint using the `endpoint` function. This example defines a GET request to '/foo' with no response entity.

```scala
/**
  * Describes an HTTP endpoint whose:
  *  - request uses verb “GET”,
  *  - URL is made of path “/foo”,
  *  - response has no entity
  */
val example = endpoint(get(path / "foo"), emptyResponse)
```

--------------------------------

### withExample

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonSchemas%24JsonSchemaOps.html

Associates an example value with the JSON schema. This example is useful for documentation generation and is typically ignored by encoder/decoder interpreters.

```APIDOC
## withExample

### Description
Include an example of a value that conforms to this schema. This example is intended for documentation interpreters and is ignored by encoder and decoder interpreters.

### Method
`def withExample(example: A): JsonSchema[A]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Returns the modified JsonSchema with the added example value.

#### Response Example
None
```

--------------------------------

### Example URL Description

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/index.html

Describes a URL starting with 'articles', followed by a String segment, and a query string with mandatory 'lang' and optional 'page' parameters.

```APIDOC
## URL Example

### Description
Describes an URL starting with a segment containing “articles”, followed by another `String` segment, and a query string containing a mandatory `Lang` parameter named “lang”, and an optional `Int` parameter named “page”.

Examples of matching URLs:

- /articles/kitchen?lang=fr
- /articles/garden?lang=en&page=2

### Value
path / "articles" / segment[String]() /? (qs[Lang]("lang") & qs[Option[Int]]("page"))
```

--------------------------------

### withExampleJsonSchema

Source: https://endpoints4s.github.io/akka-http/api/endpoints4s/akkahttp/server/JsonEntitiesFromSchemas.html

Adds an example to a JsonSchema.

```APIDOC
## def withExampleJsonSchema[A](schema: JsonSchema[A], example: A): JsonSchema[A]

### Description
Adds an example to a JsonSchema.

### Method
Not applicable (function signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### QueryStringSyntax Example

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/Urls%24QueryStringSyntax.html

Describes an URL starting with a segment containing “articles”, followed by another `String` segment, and a query string containing a mandatory `Lang` parameter named “lang”, and an optional `Int` parameter named “page”.

```APIDOC
## QueryStringSyntax Example

### Description
Describes an URL starting with a segment containing “articles”, followed by another `String` segment, and a query string containing a mandatory `Lang` parameter named “lang”, and an optional `Int` parameter named “page”.

### Example
```scala
val example = path / "articles" / segment[String]() /? (qs[Lang]("lang") & qs[Option[Int]]("page"))
```
```

--------------------------------

### withExampleRecord

Source: https://endpoints4s.github.io/akka-http/api/endpoints4s/akkahttp/server/JsonEntitiesFromSchemas.html

Adds an example to a Record type.

```APIDOC
## def withExampleRecord[A](record: Record[A], example: A): Record[A]

### Description
Adds an example to a Record type.

### Method
Not applicable (function signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### withExample

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonSchemas%24JsonSchemaOps.html

Attaches an example value to the JSON schema. This example is used by documentation interpreters to illustrate the schema's structure and is ignored by encoder and decoder interpreters.

```APIDOC
## withExample

### Description
Includes an example of a value in this schema. This example is ignored by encoder and decoder interpreters but can be shown by documentation interpreters.

### Method
`withExample(example: A): JsonSchema[A]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
`JsonSchema[A]` - The schema with the attached example value.

#### Response Example
None
```

--------------------------------

### Define GET Request

Source: https://endpoints4s.github.io/api/endpoints4s/pekkohttp/client/JsonEntitiesFromSchemas.html

Defines a GET request using the `Get` method. This is a fundamental building block for making HTTP GET requests.

```scala
__ def Get: (HttpRequest) => HttpRequest
```

--------------------------------

### Basic Authentication Example

Source: https://endpoints4s.github.io/api/endpoints4s/http4s/server/BasicAuthentication.html

This example demonstrates how to set up basic authentication for your http4s server endpoints. It includes a simple user validation mechanism.

```APIDOC
## GET /hello

### Description
An example endpoint that requires basic authentication.

### Method
GET

### Endpoint
/hello

### Parameters
#### Query Parameters
- **user** (String) - Required - The username for authentication.
- **password** (String) - Required - The password for authentication.

### Request Example
```
GET /hello?user=admin&password=password123
```

### Response
#### Success Response (200)
- **message** (String) - A success message if authentication is valid.

#### Response Example
```json
{
  "message": "Hello, admin!"
}
```

#### Error Response (401)
- **error** (String) - An error message if authentication fails.

#### Response Example
```json
{
  "error": "Invalid credentials"
}
```
```

--------------------------------

### Get

Source: https://endpoints4s.github.io/api/endpoints4s/openapi/Methods%24Get%24.html

Represents an HTTP GET method. It is an interpreter for the endpoints4s.algebra.Methods trait, specifically for the Get operation.

```APIDOC
## Get

### Description
Represents an HTTP GET method. This is part of the OpenAPI interpreter for endpoints4s.algebra.Methods.

### Method
GET

### Endpoint
Not specified in this documentation.

### Parameters
Not specified in this documentation.

### Request Example
Not specified in this documentation.

### Response
Not specified in this documentation.
```

--------------------------------

### get

Source: https://endpoints4s.github.io/play/api/endpoints4s/play/server/Endpoints.html

Defines a GET request. This method is used to specify the URL, documentation, and headers for a GET operation.

```APIDOC
## get

### Description
Defines a GET request. This method is used to specify the URL, documentation, and headers for a GET operation.

### Method
GET

### Endpoint
N/A (URL is dynamically defined)

### Parameters
#### Path Parameters
- **url** (Url[UrlP]) - Required - The URL for the get request.
- **docs** (Documentation) - Required - Documentation for the endpoint.
- **headers** (RequestHeaders[HeadersP]) - Required - Headers for the request.
- **tuplerUH** (Tupler.Aux[UrlP, HeadersP, Out]) - Required - Implicit tupler for URL and headers.
```

--------------------------------

### Basic Authentication Example

Source: https://endpoints4s.github.io/api/endpoints4s/pekkohttp/server/BasicAuthentication.html

This example demonstrates how to use basic authentication with endpoints. The `basicAuthHeaders` are defined and then used to create an endpoint that requires authentication.

```APIDOC
## Basic Authentication

### Description
This example shows how to define and use basic authentication for an endpoint. It involves defining the necessary headers for credentials and then applying them to an endpoint.

### Method
Not applicable (this is a conceptual example of endpoint definition).

### Endpoint
Not applicable (this is a conceptual example of endpoint definition).

### Request Example
```scala
val myEndpoint: Endpoint[Input, Output] = ???
val basicAuthHeaders: RequestHeaders[Credentials] = ???

val authenticatedEndpoint = myEndpoint.addHeaders(basicAuthHeaders)
```

### Response
Not applicable (this is a conceptual example of endpoint definition).
```

--------------------------------

### Basic Authentication Example

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/BasicAuthentication.html

This snippet demonstrates how to use basic authentication with the API. It includes setting up the necessary headers for authentication.

```APIDOC
## POST /login

### Description
Authenticates a user using basic authentication and returns a token.

### Method
POST

### Endpoint
/login

### Parameters
#### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
{
  "username": "user123",
  "password": "password456"
}

### Response
#### Success Response (200)
- **token** (string) - The authentication token.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

--------------------------------

### get

Source: https://endpoints4s.github.io/play/api/endpoints4s/play/server/ChunkedEntities.html

Defines a GET request. This method is used to specify the URL, documentation, and headers for a GET operation.

```APIDOC
## get

### Description
Defines a GET request. This method is used to specify the URL, documentation, and headers for a GET operation.

### Method
GET

### Endpoint
N/A (URL is defined dynamically)

### Parameters
- **url** (Url[UrlP]) - The URL for the GET request.
- **docs** (Documentation) - Documentation for the endpoint.
- **headers** (RequestHeaders[HeadersP]) - Headers for the GET request.
- **tuplerUH** (Tupler.Aux[UrlP, HeadersP, Out]) - An implicit tupler to combine URL and header parameters.

### Request Example
N/A

### Response
#### Success Response
- **Request[Out]** - Represents the GET request.
```

--------------------------------

### get

Source: https://endpoints4s.github.io/play/api/endpoints4s/play/client/MuxEndpoints.html

Defines a GET request.

```APIDOC
## get

### Description
Defines a GET request with specified URL, documentation, and headers.

### Method
GET

### Parameters
#### Path Parameters
- **url**: The URL for the GET request.
- **docs**: Documentation for the endpoint.
- **headers**: Request headers.

### Type Parameters
- **UrlP**: Type of the URL parameters.
- **HeadersP**: Type of the header parameters.
- **Out**: The output type of the request.

### Returns
A request object representing the GET operation.
```

--------------------------------

### Constructing an OK Response with Documentation

Source: https://endpoints4s.github.io/algebras/endpoints.html

An example of constructing an OK response with no entity, including additional documentation. This documentation can be used by tools to describe the response.

```scala
ok(
  emptyResponse,
  docs = Some("A response with an OK status code and no entity")
)
```

--------------------------------

### Basic Authentication Example

Source: https://endpoints4s.github.io/api/endpoints4s/http4s/server/BasicAuthentication.html

This example demonstrates how to add basic authentication headers to an existing endpoint. It shows the use of `RequestHeaders` and the `mapEndpointRequest` function to transform the request.

```APIDOC
## Basic Authentication Example

### Description
This example demonstrates how to add basic authentication headers to an existing endpoint. It shows the use of `RequestHeaders` and the `mapEndpointRequest` function to transform the request.

### Method
POST (inferred from context, not explicitly stated)

### Endpoint
(Not explicitly stated, inferred from usage)

### Parameters
#### Request Body
- **Credentials** (type inferred) - Required - The credentials for basic authentication.

### Request Example
```scala
val myEndpoint: Endpoint[Input, Output] = ???
val basicAuthHeaders: RequestHeaders[Credentials] = ???
val endpointWithAuth = mapEndpointRequest(myEndpoint, request => basicAuthHeaders.add(request))
```

### Response
(Not explicitly detailed in the provided snippet, but would typically be the response of `myEndpoint`)
```

--------------------------------

### Get

Source: https://endpoints4s.github.io/api/endpoints4s/http4s/server/ChunkedEntities.html

HTTP Method for Get.

```APIDOC
## def Get: Method

HTTP Method for Get.
```

--------------------------------

### withExampleTagged

Source: https://endpoints4s.github.io/akka-http/api/endpoints4s/akkahttp/server/JsonEntitiesFromSchemas.html

Adds an example to a Tagged type.

```APIDOC
## def withExampleTagged[A](tagged: Tagged[A], example: A): Tagged[A]

### Description
Adds an example to a Tagged type.

### Method
Not applicable (function signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### get

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/Assets.html

Helper method to perform a GET request. This simplifies the process of making GET requests by abstracting common configurations.

```APIDOC
## get

### Description
Helper method to perform GET request.

### Method
Available via the `Requests` trait.

### Parameters
- **url** (Url[UrlP]) - The URL for the GET request.
- **docs** (Documentation) - Optional documentation for the request.
- **headers** (RequestHeaders[HeadersP]) - Optional request headers.

### Type Parameters
- **UrlP**: The type of the payload carried by the URL.
- **HeadersP**: The type of the payload carried by the headers.
- **Out**: The type of the resulting request.

### Implicit Parameters
- **tuplerUH**: Tupler.Aux[UrlP, HeadersP, Out] - An implicit evidence that allows combining URL and header payloads.
```

--------------------------------

### Implementing Endpoints with Play Server

Source: https://endpoints4s.github.io/play/api/endpoints4s/play/server/Endpoints.html

This example demonstrates how to define a trait for your endpoints, implement them using the Play server interpreter, and integrate the generated routes into a Play router.

```APIDOC
## Implementing Endpoints with Play Server

### Description
This example shows how to define a trait for your endpoints, implement them using the Play server interpreter, and integrate the generated routes into a Play router.

### Example Usage

Define your endpoints in a trait that extends `algebra.Endpoints` and `algebra.JsonEntities`:
```scala
trait MyEndpoints extends algebra.Endpoints with algebra.JsonEntities {
  val inc = endpoint(get(path / "inc" ? qs[Int]("x")), jsonResponse[Int])
}
```

Implement these endpoints using `play.server.Endpoints` and `play.server.JsonEntities`:
```scala
object MyRouter extends MyEndpoints with play.server.Endpoints with play.server.JsonEntities {
  val routes = routesFromEndpoints(
    inc.implementedBy(x => x + 1)
  )
}
```

Finally, use the generated routes to define a Play router:
```scala
val router = play.api.routing.Router.from(MyRouter.routes)
```

### Source
Endpoints.scala
```

--------------------------------

### GET Request Helper

Source: https://endpoints4s.github.io/api/endpoints4s/http4s/client/ChunkedJsonEntities.html

Helper method to perform a GET request. It abstracts the process of making a GET request with specified URL and headers.

```APIDOC
## GET /url

### Description
Helper method to perform GET request.

### Method
GET

### Endpoint
`/url`

### Parameters
#### Path Parameters
- **url** (Url[UrlP]) - Required - The URL for the request.

#### Query Parameters
None explicitly documented.

#### Request Body
None.

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
- **Out** (type) - The response payload.

#### Response Example
(Not provided in source)
```

--------------------------------

### GET Request Helper

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/Requests.html

A helper method to perform GET requests. It simplifies the process of creating GET requests by abstracting common parameters.

```APIDOC
## GET Request

### Description
Helper method to perform GET request

### Method
GET

### Endpoint
Not specified (determined by the `url` parameter)

### Parameters
#### Path Parameters
None explicitly defined in this signature, but `UrlP` can contain path parameters.

#### Query Parameters
None explicitly defined in this signature, but `UrlP` can contain query parameters.

#### Headers
- **headers** (RequestHeaders[HeadersP]) - Optional - Headers for the request

### Parameters Summary
- **url** (Url[UrlP]) - The URL for the GET request
- **docs** (Documentation) - Optional - Documentation for the request
- **headers** (RequestHeaders[HeadersP]) - Optional - Request headers
```

--------------------------------

### withExampleEnum

Source: https://endpoints4s.github.io/akka-http/api/endpoints4s/akkahttp/server/JsonEntitiesFromSchemas.html

Adds an example to an Enum type.

```APIDOC
## def withExampleEnum[A](enumeration: Enum[A], example: A): Enum[A]

### Description
Adds an example to an Enum type.

### Method
Not applicable (function signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### GET Request Helper

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/BasicAuthentication.html

A helper method to perform a GET request. It simplifies the process of sending GET requests by abstracting common configurations.

```APIDOC
## get

### Description
Helper method to perform GET request.

### Method
GET

### Endpoint
[Full endpoint path with any path parameters]

### Parameters
#### Path Parameters
None explicitly defined in this snippet, but the `url` parameter can contain path parameters.

#### Query Parameters
None.

#### Request Body
None.

### Request Example
None.

### Response
#### Success Response (200)
None.

#### Response Example
None.
```

--------------------------------

### Example: Mapping Endpoint Request with Basic Auth

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/ChunkedJsonRequestEntities.html

Demonstrates how to map an endpoint's request to add basic authentication headers. Requires defining the endpoint and authentication headers.

```Scala
val myEndpoint: Endpoint[Input, Output] = ???
val basicAuthHeaders: RequestHeaders[Credentials] = ???


```

--------------------------------

### get

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonEntities.html

Helper method to perform a GET request.

```APIDOC
## get

### Description
Helper method to perform GET request.

### Method
GET

### Endpoint
N/A (Defined dynamically)

### Parameters
#### Path Parameters
- **UrlP** (type) - Description: Payload carried by url
#### Headers Parameters
- **HeadersP** (type) - Description: Payload carried by headers

### Response
#### Success Response
- Type: `Out`
```

--------------------------------

### withExampleEnum

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonEntitiesFromSchemas.html

Includes an example value within an enumeration JSON schema. This provides a concrete illustration of a valid value for the enumeration.

```APIDOC
## withExampleEnum

### Description
Includes an example value within the given enumeration JSON schema. This provides a concrete illustration of a valid value for the enumeration.

### Method
Abstract method

### Parameters
- **enumeration** (Enum[A]) - Required - The enumeration schema to include an example in.
- **example** (A) - Required - The example value to include.
```

--------------------------------

### withExampleJsonSchema

Source: https://endpoints4s.github.io/api/endpoints4s/http4s/client/JsonEntitiesFromSchemas.html

Includes an example value within the given JSON schema. This helps users understand the expected format and content of data conforming to the schema.

```APIDOC
## withExampleJsonSchema

### Description
Include an example value within the given JSON schema.

### Method
Not applicable (Scala method)

### Endpoint
Not applicable (Scala method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **JsonSchema[A]** - The JSON schema with an included example value.
```

--------------------------------

### get

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/EndpointsWithCustomErrors.html

Helper method to define a GET request.

```APIDOC
## get [UrlP, HeadersP, Out](url: Url[UrlP], docs: Documentation = None, headers: RequestHeaders[HeadersP] = emptyRequestHeaders)

### Description
Helper method to perform GET request.

### Method
GET

### Endpoint
[Full endpoint path with any path parameters]

### Parameters
#### Path Parameters
- **UrlP** - Payload carried by url.

#### Query Parameters
None specified.

#### Request Body
None specified.

#### Headers
- **headers** (RequestHeaders[HeadersP]) - Optional request headers.

### Response
- **Request[Out]** - Description not specified.
```

--------------------------------

### Query String Parameter Examples

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/ChunkedEntities.html

Illustrates how to define mandatory, optional, and repeated query string parameters.

```scala
qs[Int]("page")            // mandatory `page` parameter
qs[Option[String]]("lang") // optional `lang` parameter
qs[List[Long]]("id")       // repeated `id` parameter
```

--------------------------------

### GET Request Definition

Source: https://endpoints4s.github.io/play/api/endpoints4s/play/server/BasicAuthentication.html

Defines a GET request with URL, documentation, and request headers. This method is used to construct a request object for GET operations.

```APIDOC
## get[UrlP, HeadersP, Out](url: Url[UrlP], docs: Documentation, headers: RequestHeaders[HeadersP])(implicit tuplerUH: Tupler.Aux[UrlP, HeadersP, Out]): Request[Out]

### Description
Defines a GET request. It takes a URL, documentation, and request headers as input.

### Method
GET

### Endpoint
Not Applicable (This is a definition, not an HTTP endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Out** (type) - The type of the request output.

#### Response Example
None
```

--------------------------------

### Quick Request

Source: https://endpoints4s.github.io/api/sttp/client3/index.html

Initiates a quick request with default settings, expecting a String response.

```APIDOC
## quickRequest

### Description
Provides a convenient way to create a basic request with default settings, expecting a String as the response body.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
None directly on this method, configuration is typically done on the returned RequestT object.

### Request Example
```scala
import sttp.client3.quickRequest

val request = quickRequest.get(uri"http://example.com")
```

### Response
#### Success Response (200)
* **String** - The response body as a String.
```

--------------------------------

### get

Source: https://endpoints4s.github.io/scalaj/api/endpoints4s/scalaj/client/Endpoints.html

Defines a GET request for a given URL and documentation.

```APIDOC
## get

### Description
Defines a GET request for a given URL and documentation.

### Method
GET

### Parameters
- **url** (Url[UrlP]) - The URL for the GET request.
- **docs** (Documentation) - Documentation for this endpoint.
- **headers** (RequestHeaders[HeadersP]) - Headers for the GET request.

### Type Parameters
- **UrlP**: Type of the URL parameters.
- **HeadersP**: Type of the request headers.
- **Out**: The combined type of URL parameters and headers.

### Implicit Parameters
- **tuplerUH** (Tupler.Aux[UrlP, HeadersP, Out]) - A type class for combining URL and header types.
```

--------------------------------

### Example: Resource with ETag Header

Source: https://endpoints4s.github.io/api/endpoints4s/fetch/ChunkedRequestEntities.html

This example demonstrates defining an endpoint that returns a resource with an ETag header. It uses `responseHeader` to specify the ETag header.

```scala
val versionedResource: Endpoint[Unit, (SomeResource, String)] = \
  endpoint(
    get(path / "versioned-resource"),
    ok(
      jsonResponse[SomeResource],
      headers = responseHeader("ETag")
    )
  )
```

--------------------------------

### Get HTTP Method

Source: https://endpoints4s.github.io/api/endpoints4s/pekkohttp/server/ChunkedJsonEntities.html

Represents the HTTP GET method.

```APIDOC
## Get

### Description
Represents the HTTP GET method.

### Type
HttpMethod
```

--------------------------------

### HTTP GET method

Source: https://endpoints4s.github.io/api/endpoints4s/openapi/Assets.html

Represents the HTTP GET method.

```scala
case object Get extends Method with Product with Serializable
```

--------------------------------

### Add Basic Authentication Headers

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/LowLevelEndpoints.html

Example demonstrating how to add basic authentication headers to an endpoint's request. This involves mapping the endpoint's request to include credentials.

```scala
val myEndpoint: Endpoint[Input, Output] = ???
val basicAuthHeaders: RequestHeaders[Credentials] = ???
```

--------------------------------

### withExampleRecord

Source: https://endpoints4s.github.io/api/endpoints4s/circe/JsonSchemas.html

Includes an example value within the given record JSON schema. This helps in understanding the structure and expected data for a record.

```APIDOC
## withExampleRecord

### Description
Include an example value within the given record JSON schema.

### Method
N/A (Function Definition)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### GET Request

Source: https://endpoints4s.github.io/api/endpoints4s/openapi/BasicAuthentication.html

Helper method to define a GET request.

```APIDOC
## GET Request

### Description
Helper method to define a GET request. It takes a URL and optional headers and documentation.

### Method
GET

### Endpoint
[URL path defined by the `url` parameter]

### Parameters
#### Path Parameters
None explicitly defined in the method signature, but the `url` parameter defines the path structure.

#### Query Parameters
None explicitly defined in the method signature.

### Request Example
```json
{
  "example": "No request body for GET"
}
```

### Response
#### Success Response
- **Out** - The response type defined by the `Tupler.Aux` implicit.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### quickRequest

Source: https://endpoints4s.github.io/api/sttp/client3/index.html

Initiates a quick HTTP request, defaulting to a String response.

```APIDOC
## quickRequest

### Description
Initiates a quick HTTP request, defaulting to a String response. This is a convenient shortcut for common request scenarios.

### Method
Not specified (likely part of a request builder)

### Endpoint
Not specified

### Parameters
None

### Request Example
None

### Response
#### Success Response
- **Type**: `RequestT[Empty, String, Any]`
- **Description**: Represents a quick request that will produce a String response.

#### Response Example
None
```

--------------------------------

### GET Request

Source: https://endpoints4s.github.io/api/endpoints4s/fetch/thenable/Endpoints.html

Helper method to perform a GET request.

```APIDOC
## GET

### Description
Helper method to perform GET request.

### Method
GET

### Endpoint
[Full endpoint path with any path parameters]

### Parameters
#### Path Parameters
- **url** (Url[UrlP]) - Required - Payload carried by url
- **docs** (Documentation) - Optional - Request documentation
- **headers** (RequestHeaders[HeadersP]) - Optional - Payload carried by headers

### Response
#### Success Response (200)
- **Out** (type) - Description of the response payload
```

--------------------------------

### GET Request

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonEntitiesFromSchemas.html

Helper method to construct a GET request.

```APIDOC
## final def get[UrlP, HeadersP, Out](url: Url[UrlP], docs: Documentation = None, headers: RequestHeaders[HeadersP] = emptyRequestHeaders)(implicit tuplerUH: Tupler.Aux[UrlP, HeadersP, Out]): Request[Out]

### Description
Helper method to perform GET request.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **request** (Request[Out]) - The constructed GET request.

### Response Example
None
```

--------------------------------

### Implementing Login Endpoint with ServerAuthentication

Source: https://endpoints4s.github.io/guides/custom-authentication.html

Applies the ServerAuthentication interpreter to define a login endpoint. This example demonstrates how to implement the login logic, validating an API key and returning user information.

```scala
import endpoints4s.http4s.server

class Server
    extends server.Endpoints[IO]
    with AuthenticationEndpoints
    with ServerAuthentication[IO] {

    login.implementedBy { apiKey =>
      if (apiKey == "foobar") Some(UserInfo("Alice"))
      else None
    }

}
```

--------------------------------

### get

Source: https://endpoints4s.github.io/play/api/endpoints4s/play/client/EndpointsWithCustomErrors.html

Defines a GET request for an endpoint. Used for retrieving resources.

```APIDOC
## get

### Description
Defines a GET HTTP request for a specific URL, typically used to retrieve a resource.

### Method
GET

### Endpoint
Not specified, but the `url` parameter suggests a path.

### Parameters
#### Path Parameters
None explicitly defined, but the `url: Url[UrlP]` parameter implies path parameters might be part of the URL definition.

#### Query Parameters
None explicitly defined, but the `headers: RequestHeaders[HeadersP]` parameter might include query parameters depending on its definition.

#### Request Body
None

### Request Example
None provided.

### Response
#### Success Response
Returns a `Request[Out]` representing the GET request.

#### Response Example
None provided.
```

--------------------------------

### Add Example to Record Schema

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/JsonEntitiesFromSchemas.html

Includes an example value within the given record JSON schema.

```APIDOC
## withExampleRecord[A](record: Record[A], example: A): Record[A]

### Description
Include an example value within the given record JSON schema.

### Method
Abstract method definition.

### Endpoint
N/A (Schema modification operation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None (This is a schema modification, not an API call)

### Response
#### Success Response (N/A)
Returns the modified `Record[A]` schema with the included example.

#### Response Example
None (This is a schema modification, not an API call)
```

--------------------------------

### GET Request Helper

Source: https://endpoints4s.github.io/api/endpoints4s/fetch/Assets.html

Helper method to perform GET request.

```APIDOC
## get

### Description
Helper method to perform GET request.

### Method
GET

### Parameters
#### Path Parameters
- **url** (Url[UrlP]) - Required - Payload carried by url
#### Request Headers
- **headers** (RequestHeaders[HeadersP]) - Optional - Payload carried by headers
```

--------------------------------

### example: Option[Value]

Source: https://endpoints4s.github.io/api/endpoints4s/openapi/JsonSchemas%24DocumentedJsonSchema%24%24DocumentedRecord%24%24Lazy.html

Retrieves an example value associated with this Lazy instance, which is part of the DocumentedJsonSchema trait.

```APIDOC
## def example: Option[Value]

### Description
Retrieves an example value associated with this Lazy instance.

### Definition Classes
Lazy → DocumentedJsonSchema
```

--------------------------------

### Abstract GET Method

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/playjson/JsonEntitiesFromCodecs.html

Represents the abstract GET HTTP method.

```scala
abstract def Get: Method
```

--------------------------------

### Example Protected Resource

Source: https://endpoints4s.github.io/guides/custom-authentication.html

Example of a resource that requires a valid JWT token. Returns 'Hello user_name' on success or an Unauthorized response.

```scala
/** Some resource requiring the request to provide a valid JWT token. Returns a message
  * “Hello ''user_name''” if the request is correctly authenticated, otherwise returns
  * an `Unauthorized` HTTP response.
  */
val someResource: Endpoint[AuthenticationToken, String] = 
  authenticatedEndpoint(
    Get,
    path / "some-resource",
    emptyRequest,
    ok(textResponse)
  )
```

--------------------------------

### Defining the Get HTTP Method

Source: https://endpoints4s.github.io/api/endpoints4s/algebra/LowLevelEndpoints.html

Represents the HTTP GET method.

```scala
Get: Method
```

--------------------------------

### Basic Authentication Example

Source: https://endpoints4s.github.io/api/endpoints4s/http4s/client/BasicAuthentication.html

Demonstrates how to add basic authentication credentials to an HTTP request using http4s client. This involves encoding the username and password and including them in the Authorization header.

```APIDOC
## Basic Authentication

### Description
This endpoint demonstrates how to configure and send HTTP requests with Basic Authentication credentials using the http4s client.

### Method
GET (example, actual method depends on usage)

### Endpoint
`/your/resource` (example, actual endpoint depends on usage)

### Parameters
#### Path Parameters
None explicitly defined in this example.

#### Query Parameters
None explicitly defined in this example.

#### Request Body
None explicitly defined in this example.

### Request Example
```scala
import org.http4s.client.Client
import org.http4s.client.dsl.Http4sClientDsl
import org.http4s.headers.Authorization
import org.http4s.implicits._
import org.http4s.{BasicCredentials, Request, Uri}
import cats.effect.IO

val username = "user"
val password = "pass"

val authHeader = Authorization(BasicCredentials(username, password))

val request: Request[IO] = Request[IO](
  uri = Uri.uri("http://example.com/api/data"),
  headers = org.http4s.Headers.of(authHeader)
)

// Assuming 'client' is an instance of org.http4s.client.Client
// client.run(request).use { response => ... }.use { response => ... }
```

### Response
#### Success Response (200)
- The response will contain the data requested, typically in JSON or another format, depending on the server.

#### Response Example
```json
{
  "message": "Data retrieved successfully"
}
```

### Error Handling
- **401 Unauthorized**: If the provided credentials are invalid.
- **400 Bad Request**: If there's an issue with the request format (e.g., malformed URI, invalid headers).
- **Other HTTP Errors**: Depending on the server's configuration.
```
Tokens:
Raw