Edge types

Register an edge type

Registers an edge type and returns it. With evolve_constraints: true, widens a registered type's endpoint constraints and may rename its labels, without changing its edges. An edge type can't extend another.

POST
/edge-types

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Header parameters

X-Marfa-Instance-Id?string

The ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.

Match^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

application/json
  1. body

An edge type to register.

id*string

The identifier of the edge type, such as acme.list-member.

Length1 <= length
label?string

The name an app shows on the from end, such as Children on a parent. Leave it out and the last segment of the id makes it, such as List Member. On a change, leaving it out keeps the stored one.

reverse_label?string

The name an app shows on the to end, such as Parent on a child. Leave it out and label names both ends. On a change, leaving it out keeps the stored one; send the label to make a type two-way.

Length1 <= length
description?string

What the edge type is for.

cardinality*string

How many edges of the type an item can hold. one-to-one: each item at either end holds one. one-to-many: each item at the to end holds one. many-to-one: each item at the from end holds one. many-to-many: no limit.

Value in"one-to-one""one-to-many""many-to-one""many-to-many"
from_type_constraints?array<>

The types the item an edge points from can have: *, a type identifier or role:<name>. A type matches its subtypes. Leave it out to allow any type.

to_type_constraints?array<>

The types the item an edge points to can have, in the same form as from_type_constraints. Leave it out to allow any type.

cascade_on_delete?string

What deleting an edge's end does. cascade: deleting the from item trashes the to item. orphan: the other stays. block: the delete fails. with-hosts: the from item is trashed with its last to item, restored with any. Leave it out for orphan.

Value in"cascade""orphan""block""with-hosts"
property_schema?

The properties an edge of the type can carry, by name. Marfa checks an edge's properties against it each time the edge is written, and accepts a property it doesn't list. Leave it out for none.

reverse_name?string

The name the edge goes by when read from its to end, such as child-of for parent-of. No other edge type can use it as an ID or reverse name.

written_from?string

The end of an edge whose file writes it in a folder: from, or to under the reverse name. none means no file writes it, so a folder never renders it. to needs a reverse_name. Leave it out for from.

Value in"from""to""none"
evolve_constraints?boolean

true updates a registered type in place: widen its endpoints (keep every constraint token, or allow all types with [] or *) and change its labels. Other members stay unchanged. Omit or false to register a new type. Not stored.

Response body

About errors

Returns the widened edge type, or its unchanged definition for a repeated request.

application/json
  1. response

An edge type says how edges of that type behave: its cardinality, what a delete does to the items they join, and which item types they can join.

id*string

Unique identifier for the edge type.

label*string

The name an app shows on the from end of an edge of this type, such as Children on a parent. Not the reverse_name, which is the code name a file writes.

reverse_label*string

The name an app shows on the to end, such as Parent on a child. It is the same text as label when the relation is two-way, and an app then shows both directions as one list.

description?string

What the edge type is for.

cardinality*string

How many edges of the type an item can hold. one-to-one: each item at either end holds one. one-to-many: each item at the to end holds one. many-to-one: each item at the from end holds one. many-to-many: no limit.

Value in"one-to-one""one-to-many""many-to-one""many-to-many"
from_type_constraints*array<string>

The types the item an edge points from can have: *, a type identifier or role:<name>. A type matches its subtypes.

to_type_constraints*array<string>

The types the item an edge points to can have, in the same form as from_type_constraints.

cascade_on_delete*string

What deleting an edge's end does. cascade: deleting the from item trashes the to item. orphan: the other stays. block: the delete fails. with-hosts: the from item is trashed with its last to item, restored with any.

Value in"cascade""orphan""block""with-hosts"
property_schema*

The properties an edge of the type can carry, by name. Marfa checks an edge's properties against it each time the edge is written, and accepts a property it doesn't list.

reverse_name?string

The name the edge goes by when read from its to end, such as child-of for parent-of.

written_from*string

The end of an edge whose file writes it in a folder: from, or to under the reverse name. none means no file writes it, so a folder never renders it.

Value in"from""to""none"
shipped*boolean

true if Marfa ships the edge type: it exists on every instance, and you can't register or delete it. false for one registered through POST /edge-types.

acyclic*boolean

true if the server refuses an edge of this type that closes a cycle through other edges of the type. Every edge type refuses an edge from an item to itself.

flat*boolean

true if the server refuses an edge of this type from an item whose type its to_type_constraints admit, so an item that an edge of the type can point to never points from one.

Returns the new edge type.

application/json
  1. response

An edge type says how edges of that type behave: its cardinality, what a delete does to the items they join, and which item types they can join.

id*string

Unique identifier for the edge type.

label*string

The name an app shows on the from end of an edge of this type, such as Children on a parent. Not the reverse_name, which is the code name a file writes.

reverse_label*string

The name an app shows on the to end, such as Parent on a child. It is the same text as label when the relation is two-way, and an app then shows both directions as one list.

description?string

What the edge type is for.

cardinality*string

How many edges of the type an item can hold. one-to-one: each item at either end holds one. one-to-many: each item at the to end holds one. many-to-one: each item at the from end holds one. many-to-many: no limit.

Value in"one-to-one""one-to-many""many-to-one""many-to-many"
from_type_constraints*array<string>

The types the item an edge points from can have: *, a type identifier or role:<name>. A type matches its subtypes.

to_type_constraints*array<string>

The types the item an edge points to can have, in the same form as from_type_constraints.

cascade_on_delete*string

What deleting an edge's end does. cascade: deleting the from item trashes the to item. orphan: the other stays. block: the delete fails. with-hosts: the from item is trashed with its last to item, restored with any.

Value in"cascade""orphan""block""with-hosts"
property_schema*

The properties an edge of the type can carry, by name. Marfa checks an edge's properties against it each time the edge is written, and accepts a property it doesn't list.

reverse_name?string

The name the edge goes by when read from its to end, such as child-of for parent-of.

written_from*string

The end of an edge whose file writes it in a folder: from, or to under the reverse name. none means no file writes it, so a folder never renders it.

Value in"from""to""none"
shipped*boolean

true if Marfa ships the edge type: it exists on every instance, and you can't register or delete it. false for one registered through POST /edge-types.

acyclic*boolean

true if the server refuses an edge of this type that closes a cycle through other edges of the type. Every edge type refuses an edge from an item to itself.

flat*boolean

true if the server refuses an edge of this type from an item whose type its to_type_constraints admit, so an item that an edge of the type can point to never points from one.

  • validation_error: a field is invalid, such as a bad id or reverse_name, a role: naming no role, or written_from: to with no reverse_name, or extends is set.
  • missing_required_field: id or cardinality is missing.
  • invalid_schema: a property's type isn't a field type, or the body has a key the schema doesn't define (details.errors names each path).
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • forbidden: you don't have metadata.edge_types:write.
  • edge_type_not_permitted: your edge map doesn't grant write on id or reverse_name. details.edge_type names it.
  • type_not_permitted: the edge type cascades on delete and holds edges that point to items of a type you can't write. details.grant names the missing grant.
application/json
  1. response

An error response.

error*

What went wrong.

edge_type_not_found: constraint evolution names no registered edge type.

application/json
  1. response

An error response.

error*

What went wrong.

request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.

application/json
  1. response

An error response.

error*

What went wrong.

conflict: id is the name of an edge type Marfa ships, id or reverse_name is already the ID or reverse name of an edge type, or reverse_name equals id, or constraint evolution would remove a constraint token without allowing every type or change a definition member other than the labels.

application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

request_too_large: the request body is larger than this instance accepts.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X POST 'http://localhost:8600/edge-types' \  -H 'Content-Type: application/json' \  -d '{  "id": "string",  "cardinality": "one-to-one"}'
About errors
{  "id": "acme.deal-contact",  "label": "Contact",  "reverse_label": "Deals",  "cardinality": "many-to-many",  "from_type_constraints": [    "acme.deal"  ],  "to_type_constraints": [    "acme.contact"  ],  "cascade_on_delete": "orphan",  "property_schema": {},  "written_from": "from",  "shipped": false,  "acyclic": false,  "flat": false}