Metadata API

The metadata API allows you to store additional information about a resource such as the name and up to 49 other custom key-value pairs.

Metadata Lifecycle

Metadata is created when a resource is added and will listen system-wide for destructive events. When a resource is removed, all metadata associated with that resource will also be removed.

Custom key-value pairs can be removed from a metadata object by performing a PUT and setting the value to null.

The Metadata Object

  • Name
    resource_id
    Type
    uuid
    Description

    The unique identifier of the resource that the metadata belongs to.

  • Name
    type
    Type
    string
    Description

    This is the type of resource. It is a dot delimited lowercase string with a maximum length of 100 characters.

  • Name
    metadata
    Type
    object
    Description

    An object with key-value pairs. There is an upper limit of 50 key-value pairs per resource, including the name property.

  • Name
    metadata.name
    Type
    string
    Description

    This is the name of the resource. It should always be present with a maximum length of 50 characters.

  • Name
    metadata.*
    Type
    key+value
    Description

    These are custom key-value pairs that can be used to store additional information about the resource. The key can be a maximum of 50 characters and the value can be a maximum of 100 characters. Values should be strings, integers or booleans.

  • Name
    search
    Type
    string
    Description

    Query parameter when searching values of metadata. Search is case insensitive and will match partial strings.

  • Name
    matched_on
    Type
    array
    Description

    This is an array of keys that were matched when searching for a resource.

The Metadata Object

{
    "resource_id": "c66b3b16-96f6-486d-9d0c-a6c39dad9a6c",
    "type": "site",
    "metadata": {
        "name": "Home WIFI Router",
        "Room": "Lounge" // custom key-value pair
    },
    "matched_on": [ // only present when searching
        "name"
    ]
}
GET/v1/metadata

Fetching Metadata

This endpoint can be used to fetch all metadata for the logged in user or a specific resource. When fetching all metadata an optional search parameter can be used to filter the results. The search parameter will be matched against the value of the metadata key-value pairs. The search is case insensitive and will match partial strings.

Parameters

No parameters are required for this endpoint.

Example requests

# Make GET request to /v1/metadata

curl -G https://api.mikrocloud.com/v1/metadata \
-H "Authorization: Bearer {token}"

Example responses

[
    {
        "resource_id": "7de9960f-22f5-4658-aa33-8878c556220d",
        "type": "site.wan",
        "metadata": {
            "name": "Telstra 5G",
            "Account Number": "HK-234234-232EFR"
        }
    },
    {
        "resource_id": "c66b3b16-96f6-486d-9d0c-a6c39dad9a6c",
        "type": "site",
        "metadata": {
            "name": "Home WIFI Router",
            "Room": "Lounge"
        }
    }
]
POST/v1/metadata

Create Metadata

If a resource already exists with the same resource_id and type for the logged in user, the metadata will be updated / overwritten.

Parameters

  • Name
    resource_id
    Type
    uuid
    Required
    Required
    Description

    This is the unique identifier of the resource. It should be a valid v4 UUID.

  • Name
    type
    Type
    string
    Required
    Required
    Description

    This is a representation of the type of resource. It should be dot delimited lowercase string with a maximum length of 100 characters.

  • Name
    metadata.name
    Type
    string
    Required
    Required
    Description

    This is the name of the resource. It should always be present and be a string with a maximum length of 50 characters.

  • Name
    metadata.*
    Type
    key+value
    Required
    Optional
    Description

    The key can be a maximum of 50 characters and the value can be a maximum of 100 characters. A single resource can have a maximum of 49 custom key-value pairs.

Request

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
    "resource_id": "7de9960f-22f5-4658-aa33-8878c556220d",
    "type": "site.wan",
    "metadata": {
        "name": "Telstra 5G"
    }
}' https://api.mikrocloud.com/v1/metadata

Response

{
    "resource_id": "7de9960f-22f5-4658-aa33-8878c556220d",
    "type": "site.wan",
    "metadata": {
        "name": "Telstra 5G"
    }
}
PUT/v1/metadata/:resource_id

Update Metadata

Parameters

  • Name
    metadata.name
    Type
    string
    Required
    Optional
    Description

    This is the name of the resource. It should always be present and be a string with a maximum length of 50 characters.

  • Name
    metadata.*
    Type
    key+value
    Required
    Optional
    Description

    The key can be a maximum of 50 characters and the value can be a maximum of 100 characters. A single resource can have a maximum of 49 custom key-value pairs.

Remove a key-value pair by setting its value to null.

Request

curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
    "type": "site.wan",
    "metadata": {
        "name": "Telstra 5G",
        "Account Number": "34234-232EFR"
    }
}' \
https://api.mikrocloud.com/v1/metadata/7de9960f-22f5-4658-aa33-8878c556220d

Response

{
    "resource_id": "7de9960f-22f5-4658-aa33-8878c556220d",
    "type": "site.wan",
    "metadata": {
        "name": "Telstra 5G",
        "Account Number": "34234-232EFR"
    }
}
GET/v1/metadata/keys

Get Metadata Keys

Whenever a new metadata key is added to a resource, it will be added to the list of available keys. This endpoint can be used to fetch all available keys. The keys are sorted alphabetically.

Keys will be cached if this endpoint is called more than twice in a 5 minute period. Cache is persisted for 5 minutes.

Request

curl -G https://api.mikrocloud.com/v1/metadata/keys \
-H "Authorization: Bearer {token}"

Response

["Account Number", "Room", "Name"]

Was this page helpful?