Skip to content

[API] Add HATEOAS Links for Discoverability #75

@fentz26

Description

@fentz26

Problem

No hypermedia links in responses:

  • Clients must hardcode URLs
  • API not self-documenting
  • Navigation requires out-of-band knowledge

Proposed Solution

Link Headers and Body Links

type TaskResponse struct {
    Task
    Links map[string]Link `json:"_links"`
}

type Link struct {
    Href   string `json:"href"`
    Method string `json:"method,omitempty"`
    Title  string `json:"title,omitempty"`
}

// Example response
{
    "id": "task-123",
    "title": "Implement feature",
    "status": "pending",
    "_links": {
        "self": {"href": "/v1/tasks/task-123"},
        "claim": {"href": "/v1/tasks/task-123/claim", "method": "POST"},
        "runs": {"href": "/v1/tasks/task-123/runs"},
        "parent": {"href": "/v1/tasks"}
    }
}

Acceptance Criteria

  • _links object in all responses
  • self link always present
  • Related resource links
  • Action links with methods
  • Link header for pagination

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions