Skip to content

Commit

Permalink
Add route-options documentation
Browse files Browse the repository at this point in the history 
Add documentation for the route options object, and its supported fields.
  • Loading branch information
@hoffmaen
hoffmaen committed Nov 13, 2024
1 parent da667dd commit d5e369c
Show file tree
Hide file tree
Showing 6 changed files with 66 additions and 32 deletions.
12 changes: 12 additions & 0 deletions docs/v3/source/includes/api_resources/_routes.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@
"protocol": "tcp"
}
],
"options": {
"lb_algo": "round-robin"
},
"metadata": {
"labels": <%= metadata.fetch(:labels, {}).to_json(space: ' ', object_nl: ' ')%>,
"annotations": <%= metadata.fetch(:annotations, {}).to_json(space: ' ', object_nl: ' ')%>
Expand Down Expand Up @@ -124,6 +127,9 @@
"protocol": "http1"
}
],
"options": {
"lb_algo": "round-robin"
},
"metadata": {
"labels": {},
"annotations": {}
Expand Down Expand Up @@ -212,3 +218,9 @@
"protocol": "http2"
}
<% end %>

<% content_for :route_options do %>
{
"lb_algo": "round-robin"
}
<% end %>
26 changes: 15 additions & 11 deletions docs/v3/source/includes/resources/routes/_create.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@ curl "https://api.example.org/v3/routes" \
"data": { "guid": "space-guid" }
}
},
"options": {
"lb_algo": "round-robin"
}
"metadata": {
"labels": { "key": "value" },
"annotations": { "note": "detailed information"}
Expand All @@ -44,20 +47,21 @@ Content-Type: application/json

#### Required parameters

| Name | Type | Description |
| ----------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route; routes can only be mapped to destinations in that space |
| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route |
| Name | Type | Description |
|--------------------------|------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route; routes can only be mapped to destinations in that space |
| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route |

#### Optional parameters

| Name | Type | Description |
| ------------------------ | ----------------------------------- | --------------------------------- |
| **host** | _string_ | The host component for the route; not compatible with routes specifying the `tcp` protocol |
| **path** | _string_ | The path component for the route; should begin with a `/` and not compatible with routes specifying the `tcp` protocol |
| **port** | _integer_ | The port the route will listen on; only compatible with routes leveraging a domain that supports the `tcp` protocol. For `tcp` domains, a port will be randomly assigned if not specified
| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route |
| **metadata.labels** | [_label object_](#labels) | Labels applied to the route |
| Name | Type | Description |
|--------------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **host** | _string_ | The host component for the route; not compatible with routes specifying the `tcp` protocol |
| **path** | _string_ | The path component for the route; should begin with a `/` and not compatible with routes specifying the `tcp` protocol |
| **port** | _integer_ | The port the route will listen on; only compatible with routes leveraging a domain that supports the `tcp` protocol. For `tcp` domains, a port will be randomly assigned if not specified |
| **options** | [_route option object_](#the-route-options-object) | Options applied to the route |
| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route |
| **metadata.labels** | [_label object_](#labels) | Labels applied to the route |

#### Permitted roles

Expand Down
33 changes: 17 additions & 16 deletions docs/v3/source/includes/resources/routes/_object.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,20 @@ Example Route object
<%= yield_content :single_route %>
```

| Name | Type | Description
| -------------- | ------------------------ | ------------------------------------------------------
| **guid** | _uuid_ | Unique identifier for the route
| **created_at** | _[timestamp](#timestamps)_ | The time with zone when the object was created
| **updated_at** | _[timestamp](#timestamps)_ | The time with zone when the object was last updated
| **protocol** | _string_ | The protocol supported by the route, based on the route's domain configuration. Valid protocols are `http` and `tcp`
| **host** | _string_ | The hostname for the route; not compatible with routes specifying the `tcp` protocol;<br>must be either a wildcard (*) or be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_)
| **path** | _string_ | The path for the route; not compatible with routes specifying the `tcp` protocol;<br>must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from [RFC 2396](https://tools.ietf.org/html/rfc2396)
| **port** | _integer or `null`_ | The port that the route listens on. Only compatible with routes specifying the `tcp` protocol
| **url** | _string_ | The URL for the route; URLs of protocol `http` are a combination of host, domain name, and path; URLs of protocol `tcp` are a combination of domain name and port
| **destinations** | array of [_destination objects_](#the-destination-object) | List of destinations for the route
| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route. Routes can only be mapped to destinations in that space
| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route
| **metadata.labels** | [_label object_](#labels) | Labels applied to the route
| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route
| **links** | [_links object_](#links) | Links to related resources
| Name | Type | Description |
|--------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **guid** | _uuid_ | Unique identifier for the route |
| **created_at** | _[timestamp](#timestamps)_ | The time with zone when the object was created |
| **updated_at** | _[timestamp](#timestamps)_ | The time with zone when the object was last updated |
| **protocol** | _string_ | The protocol supported by the route, based on the route's domain configuration. Valid protocols are `http` and `tcp` |
| **host** | _string_ | The hostname for the route; not compatible with routes specifying the `tcp` protocol;<br>must be either a wildcard (*) or be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_) |
| **path** | _string_ | The path for the route; not compatible with routes specifying the `tcp` protocol;<br>must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from [RFC 2396](https://tools.ietf.org/html/rfc2396) |
| **port** | _integer or `null`_ | The port that the route listens on. Only compatible with routes specifying the `tcp` protocol |
| **url** | _string_ | The URL for the route; URLs of protocol `http` are a combination of host, domain name, and path; URLs of protocol `tcp` are a combination of domain name and port |
| **destinations** | array of [_destination objects_](#the-destination-object) | List of destinations for the route |
| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route. Routes can only be mapped to destinations in that space |
| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route |
| **options** | [_route option object_](#the-route-options-object) | Options applied to the route |
| **metadata.labels** | [_label object_](#labels) | Labels applied to the route |
| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route |
| **links** | [_links object_](#links) | Links to related resources |
12 changes: 12 additions & 0 deletions docs/v3/source/includes/resources/routes/_route_options_object.md.erb
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
### The route options object

```
Example Route-Options object
```
```json
<%= yield_content :route_options %>
```

| Name | Type | Description |
|-------------|----------|----------------------------------------------------------------------------------------------------------|
| **lb_algo** | _string_ | The load balancer associated with this route. Valid algorithms are 'round-robin' and 'least-connections' |
14 changes: 9 additions & 5 deletions docs/v3/source/includes/resources/routes/_update.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ curl "https://api.example.org/v3/routes/[guid]" \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"options": {
"lb_algo": "round-robin"
}
"metadata": {
"labels": {"key": "value"},
"annotations": {"note": "detailed information"}
Expand All @@ -33,14 +36,15 @@ Content-Type: application/json

#### Optional parameters

| Name | Type | Description | Default |
| ----------- | -------- | ------------------------------------------------------------------------ | ------- |
| **metadata.labels** | [_label object_](#labels) | Labels applied to the route | |
| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route | |
| Name | Type | Description | Default |
|----------------------------|-----------------------------------------------------|----------------------------------|---------|
| **options** | [_route option object_](#the-route-options-object) | Options applied to the route | |
| **metadata.labels** | [_label object_](#labels) | Labels applied to the route | |
| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route | |

#### Permitted roles

|
|
----- |
Admin |
Space Developer |
Expand Down
1 change: 1 addition & 0 deletions docs/v3/source/index.html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,7 @@ includes:
- resources/routes/header
- resources/routes/object
- resources/routes/destination_object
- resources/routes/route_options_object
- resources/routes/create
- resources/routes/get
- resources/routes/list
Expand Down

0 comments on commit d5e369c

Please sign in to comment.