Skip to content
FALCON CORETECHNOLOGIES

// Lesson 47 of 49 · Automation and programmability

REST APIs

HTTP methods and CRUD, URIs, status codes, headers and authentication — how software talks to network controllers and devices.
2 min read#rest#api#http

A REST API lets a program ask a controller or device for data, or change it, using ordinary HTTP(S) requests.

Anatomy of a request

GET https://controller.corp.example/api/v1/network-device?hostname=SW1
Accept: application/json
Authorization: Bearer eyJhbGciOi...
  • Method — what to do.
  • URI — which resource: scheme, host, path and optional query parameters.
  • Headers — metadata: authentication, content type.
  • Body — data for POST/PUT/PATCH, usually JSON.

Methods and CRUD

CRUD HTTP method Example
Create POST Add a new VLAN
Read GET List devices
Update PUT (replace) / PATCH (modify part) Change an interface description
Delete DELETE Remove a VLAN

REST is stateless: each request carries everything the server needs (including authentication).

Status codes

Code Meaning
200 OK Success, data returned
201 Created Resource created (POST)
204 No Content Success, nothing to return
400 Bad Request Malformed request
401 Unauthorized Missing or invalid credentials
403 Forbidden Authenticated, but not allowed
404 Not Found Resource does not exist
500 Internal Server Error The server failed

Rule of thumb: 2xx success, 4xx your request is wrong, 5xx the server is wrong.

Authentication

Common methods: HTTP Basic (username/password, only over HTTPS), API keys, and tokens — you log in once, receive a token, and send it in an Authorization header with each request until it expires.

Trying it

Tools such as Postman, curl or a few lines of Python let you call an API:

$ curl -s -H "Accept: application/json" -H "Authorization: Bearer $TOKEN" \
    https://controller.corp.example/api/v1/network-device

Key points

  • Request = method + URI + headers (+ body).
  • POST create, GET read, PUT/PATCH update, DELETE delete.
  • 2xx success, 4xx client error, 5xx server error; 401 vs 403.
  • APIs are stateless; tokens are sent with every request.

Sign in to save your lesson progress across devices. You can read every published lesson without an account.