A REST API lets a program do over HTTP what you'd do in a web browser, but getting back data (usually JSON) instead of a web page. It's how scripts talk to a controller's northbound API.
CRUD and HTTP methods
| Action (CRUD) | HTTP method | Example |
|---|---|---|
| Create | POST | Add a new VLAN |
| Read | GET | List the interfaces |
| Update | PUT / PATCH | Change an interface's description |
| Delete | DELETE | Remove a VLAN |
Status codes
| Code | Means |
|---|---|
| 2xx (200 OK, 201 Created) | It worked |
| 4xx (400, 401, 403, 404) | Your fault: bad request, not authenticated, not allowed, not found |
| 5xx (500, 503) | The server's fault |
A request and its answer
A GET to a controller, with a token to prove who you are, might return:
GET /api/v1/interface/GigabitEthernet0/1
Authorization: Bearer eyJhbGciOi...
Accept: application/json{
"interface": {
"name": "GigabitEthernet0/1",
"enabled": true,
"speed": 1000,
"addresses": [
{ "ip": "10.1.1.1", "mask": "255.255.255.0" }
],
"vlans": [1, 10, 20]
}
}Authentication is usually a token: you log in once (POST your username and password), get a token back, and send it with every later request. REST is stateless - each request carries everything the server needs.
Remember: GET=read, POST=create, PUT/PATCH=update, DELETE=delete. 2xx good, 4xx your fault, 5xx server's fault. Log in once, then send a token with each request.