Skip to content

Commit 754e43e

Browse files
jeremystretchjeremystretch
committed
Closes #35: Add REST API documentation & examples
1 parent 344e16c commit 754e43e

File tree

2 files changed

+134
-0
lines changed

2 files changed

+134
-0
lines changed

‎docs/rest-api.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Using the REST API
2+
3+
This plugin includes support for activating and deactivating branches via the REST API in addition to conventional creation, modification, and deletion operations.
4+
5+
!!! tip "API Token Required"
6+
You'll need a valid NetBox REST API token to follow any of the examples shown here. API tokens can be provisioned by navigating to the API tokens list in the user menu.
7+
8+
## Creating a Branch
9+
10+
Branches are created in a manner similar to most objects in NetBox. A `POST` request (including a valid authentication token) is sent to the `branches/` API endpoint with the desired attributes, such as name and description:
11+
12+
```no-highlight title="Request"
13+
curl -X POST \
14+
-H "Authorization: Token $TOKEN" \
15+
-H "Content-Type: application/json" \
16+
-H "Accept: application/json; indent=4" \
17+
http://netbox:8000/api/plugins/branching/branches/ \
18+
--data '{"name": "Branch 1", "description": "My new branch"}'
19+
```
20+
21+
```json title="Response"
22+
{
23+
"id": 2,
24+
"url": "http://netbox:8000/api/plugins/branching/branches/2/",
25+
"display": "Branch 1",
26+
"name": "Branch 1",
27+
"status": "new",
28+
"owner": {
29+
"id": 1,
30+
"url": "http://netbox:8000/api/users/users/1/",
31+
"display": "admin",
32+
"username": "admin"
33+
},
34+
"description": "My new branch",
35+
"schema_id": "td5smq0f",
36+
"last_sync": null,
37+
"merged_time": null,
38+
"merged_by": null,
39+
"comments": "",
40+
"tags": [],
41+
"custom_fields": {},
42+
"created": "2024-08-12T17:07:46.196956Z",
43+
"last_updated": "2024-08-12T17:07:46.196970Z"
44+
}
45+
```
46+
47+
Once a new branch has been created, it will be provisioned automatically, just as when one is created via the web UI. The branch's status will show "ready" when provisioning has completed.
48+
49+
Once provisioned, branches can be modified and deleted via the `/api/plugins/branching/branches/<id>/` endpoint, similar to most objects in NetBox.
50+
51+
## Activating a Branch
52+
53+
Unlike the web UI, where a user's selected branch remains active until it is changed, the desired branch must be specified with each REST API request. This is accomplished by including the `X-NetBox-Branch` HTTP header specifying the branch's schema ID.
54+
55+
```no-highlight
56+
X-NetBox-Branch: $SCHEMA_ID
57+
```
58+
59+
!!! tip "Schema IDs"
60+
The schema ID for a branch can be found in its REST API representation or on its detail view in the web UI. This is a pseudorandom eight-character alphanumeric identifier generated automatically when a branch is created. Note that the value passed to the HTTP header **does not include** the `branch_` prefix, which comprises part of the schema's name in the underlying database.
61+
62+
The example below returns all site objects that exist within the branch with schema ID `td5smq0f`:
63+
64+
```no-highlight title="Request"
65+
curl -X POST \
66+
-H "Authorization: Token $TOKEN" \
67+
-H "Content-Type: application/json" \
68+
-H "Accept: application/json; indent=4" \
69+
-H "X-NetBox-Branch: td5smq0f" \
70+
http://netbox:8000/api/dcim/sites/
71+
```
72+
73+
The branch is effectively "deactivated" for future API requests by simply omitting the header.
74+
75+
!!! note
76+
The `X-NetBox-Branch` header is required only when making changes to NetBox objects within the context of an active branch. It is **not** required when creating, modifying, or deleting a branch itself.
77+
78+
## Syncing & Merging Branches
79+
80+
Several REST API endpoints are provided to handle synchronizing, merging, and reverting branches:
81+
82+
| Endpoint | Description |
83+
|-----------------------------------------------|---------------------------------------------|
84+
| `/api/plugins/branching/branches/<id>/sync/` | Synchronize changes from main to the branch |
85+
| `/api/plugins/branching/branches/<id>/merge/` | Merge a branch into main |
86+
| `/api/plugins/branching/branches/<id>/revert/` | Revert a previously merged branch |
87+
88+
To synchronize updates from main into a branch, send a `POST` request to the desired branch's `sync/` endpoint.
89+
90+
This endpoint requires a `commit` argument: Setting this to `false` effects a dry-run, where the changes to the branch are automatically rolled back at the end of the job. (This can be helpful to check for potential errors before committing to a set of changes.)
91+
92+
```no-highlight title="Request"
93+
curl -X POST \
94+
-H "Authorization: Token $TOKEN" \
95+
-H "Content-Type: application/json" \
96+
-H "Accept: application/json; indent=4" \
97+
http://netbox:8000/api/plugins/branching/branches/2/sync/ \
98+
--data '{"commit": true}'
99+
```
100+
101+
If successful, this will return data about the background job that has been enqueued to handle the synchronization of data. This job can be queried to determine the progress of the synchronization.
102+
103+
```json title="Response"
104+
{
105+
"id": 4,
106+
"url": "http://netbox:8000/api/core/jobs/4/",
107+
"display_url": "http://netbox:8000/core/jobs/4/",
108+
"display": "f0c6dea2-d5bb-4683-851e-2ac705510af4",
109+
"object_type": "netbox_branching.branch",
110+
"object_id": 2,
111+
"name": "Sync branch",
112+
"status": {
113+
"value": "pending",
114+
"label": "Pending"
115+
},
116+
"created": "2024-08-12T17:27:57.448405Z",
117+
"scheduled": null,
118+
"interval": null,
119+
"started": null,
120+
"completed": null,
121+
"user": {
122+
"id": 1,
123+
"url": "http://netbox:8000/api/users/users/1/",
124+
"display": "admin",
125+
"username": "admin"
126+
},
127+
"data": null,
128+
"error": "",
129+
"job_id": "f0c6dea2-d5bb-4683-851e-2ac705510af4"
130+
}
131+
```
132+
133+
This same pattern can be followed to merge and revert branches via their respective API endpoints, listed above.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ nav:
4242
- Creating a Branch: 'using-branches/creating-a-branch.md'
4343
- Syncing & Merging: 'using-branches/syncing-merging.md'
4444
- Reverting a Branch: 'using-branches/reverting-a-branch.md'
45+
- REST API: 'rest-api.md'
4546
- Data Model:
4647
- Branch: 'models/branch.md'
4748
- BranchEvent: 'models/branchevent.md'

0 commit comments

Comments
 (0)