Links Protocol

Server responses MAY include typed relations to inform clients of related resources available from the current resource state. These typed relations together form the Standard’s “Links Protocol”. Example uses of the Links Protocol include declaration of:

• next and previous cursors during pagination
• related resources (nearby location, same ownership, etc)
• actions that may be executed on the current resource

Example

{
    "links": {
        "self": "http://api.trimble.com/assets/32",
        "parent": {
            "href": "http://api.trimble.com/assets/30",
            "rel": "assets:parentDevice",
            "title":"The parent device that controls this device."
        },
        "activate": {
            "href": "http://api.trimble.com/assets/32/activate",
            "rel": "assets:activate",
            "title":"Activate this device for license assignment and use."
        }
    }
}

Schema

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://developer.trimble.com/specifications/latest/links-protocol",
    "title": "Trimble API Standard Links Container",
    "description": "A document or resource object containing a 'links' key with N number of link members.",
    "type": "object",
    "properties": {
        "links": {
            "type": "object",
            "description": "The members of a links object MUST be links.",
            "additionalProperties": {
                "$ref": "#/$defs/link"
            }
        }
    },
    "required": [
        "links"
    ],
    "$defs": {
        "link": {
            "title": "Link",
            "description": "A link MUST be represented as either a string or link object",
            "oneOf": [
                {
                    "type": "string",
                    "format": "uri-reference",
                    "description": "A string containing the link's URL (URI-reference)."
                },
                {
                    "type": "object",
                    "title": "Link Object",
                    "required": [
                        "href"
                    ],
                    "properties": {
                        "href": {
                            "type": "string",
                            "format": "uri-reference",
                            "description": "A string containing the link's URL."
                        },
                        "rel": {
                            "type": "string",
                            "description": "A string indicating the link's relation type."
                        },
                        "title": {
                            "type": "string",
                            "description": "A human-readable label for the destination of the link."
                        }
                    },
                    "additionalProperties": true
                }
            ]
        }
    }
}