Calling Your New API

Now that you've got a basic HTTP API setup, you can start making API requests to it.

API Documentation

You should now be able to access the API docs at http://localhost:8080/docs, which should display a nice UI (scalar) for exploring the API, and executing sample requests:

Sample Requests with Curl

Here are a few sample requests that you can execute with curl.

Create a new user (note the id field in the response, we'll use that in further requests)

curl --request POST \
  --url 'http://localhost:8080/users?pretty=true' \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "lrstanley",
  "display_name": "Liam Stanley",
  "email": "lrstanley@example.com"
}'

{
    "id": 4294967297,
    "username": "lrstanley",
    "display_name": "Liam Stanley",
    "email": "lrstanley@example.com",
    "edges": {}
}

Create a new pet who is owned by the user we just created

curl --request POST \
  --url 'http://localhost:8080/pets?pretty=true' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Riley",
  "age": 2,
  "type": "DOG",
  "owner": 4294967297
}'

{
    "id": 1,
    "name": "Riley",
    "age": 2,
    "type": "DOG",
    "edges": {
        "owner": {
            "id": 4294967297,
            "username": "lrstanley",
            "display_name": "Liam Stanley",
            "email": "lrstanley@example.com",
            "edges": {}
        }
    }
}

Notice that the response includes the edges field. This is because we've added the owner edge to be eager-loaded in the schema, as shown below:

internal/database/schema/pet.go

func (Pet) Edges() []ent.Edge {
    return []ent.Edge{
        // [...]
        edge.From("owner", User.Type).
            Ref("pets").
            Unique().
            Comment("The user that owns the pet.").
            Annotations(
                entrest.WithEagerLoad(true),
                entrest.WithFilter(entrest.FilterEdge),
            ),
        // [...]
    }
}

Now query the pets that the user owns

This uses the auto-generated edge endpoint on the User schema.

curl --request GET \
  --url 'http://localhost:8080/users/4294967297/pets?pretty=true'

{
    "page": 1,
    "total_count": 1,
    "last_page": 1,
    "is_last_page": true,
    "content": [
        {
            "id": 1,
            "name": "Riley",
            "age": 2,
            "type": "DOG",
            "edges": {
                "owner": {
                    "id": 4294967297,
                    "username": "lrstanley",
                    "display_name": "Liam Stanley",
                    "email": "lrstanley@example.com",
                    "edges": {}
                }
            }
        }
    ]
}