Mate's CCNA Notes

Day 61 - REST API61. Nap - REST API

5 min read

Jeremy’s IT Lab lecture video:

Day 61 - REST API

Commands

No Commands :)

REST API Info

An API is a software interface that allows two applications to communicate with each other.

  • APIs are essential not just for network automation, but for all kinds of applications.
  • IN SDN architecture, APIs are used to communicate between apps and the SDN Controller (via the NBI), and between the SDN Controller and the network devices (via the SBI).
  • The NBI typically uses REST APIs
  • Netconf and Restconf are popular Southbound APIs.

CRUD

CRUD (Create, Read, Update, Delete) refers to the operations we perform using REST APIs.

  1. Create
    • Create operations are used to create new variables and set their initial values.
    • Example: Create variable “ip_address” and set the value to “10.1.1.1”
  2. Read
    • Read operations are used to retrieve the value of a variable.
    • Example: What is the value of variable “ip_address”?
  3. Update
    • Update operations are used to change the value of variable.
    • Example: Change the value of variable “ip_address” to “10.2.3.4”
  4. Delete
    • Delete operations are used to delete variables.
    • Example: Delete variables “ip_address”.

  • HTTP uses verbs (aka. methods) to map these CRUD operations.
  • REST APIs typically use HTTP.
PurposeCRUD OperationHTTP Verb
Create new variableCreatePOST
Retrieve value of a valueReadGET
Change the value of variableUpdatePUT, PATCH
Delete variableDeleteDELETE

HTTP Request

When an HTTP client sends a request to an HTTP server, the HTTP header includes information like this:

  • An HTTP Verb (ie. GET).
  • A URI (Uniform Resource Identifier), indicating the resource it is trying to access.
HTTP Request Example
  • A URI consists of three different parts
    1. Scheme
    2. Authority
    3. Paths
  • Example: https://sandboxdnac.cisco.com/dna/intent/api/v1/network-device
    • Scheme: https
    • Authority: sandboxdnac.cisco.com
    • Paths: dna/intent/api/v1/network-device

HTTP Request - Headers

  • HTTP request can include additional headers which pass additional information to the server.
Example HTTP Request with extra headers
  • An example would an Accept header, which informs the server about the type(s) of data that can be sent back to the client.
  • When a REST client makes an API call (request) to a REST server, it will send an HTTP request like the one above.
  • REST APIs don’t have to use HTTP specifically for communication, although HTTP is the most common choice.

HTTP Response

  • The server’s response will include a status code indicating the request succeeded or failed, as well as the other details.
  • The first digit indicates the class of the response:
    1. 1xx Informational
      • The request was received, continuing process.
    2. 2xx Successful
      • The request was successfully received, understood, and accepted.
    3. 3xx Redirection
      • Further action needs to be taken in order to complete the request.
    4. 4xx Client Error
      • The request contains bad syntax or cannot be fulfilled.
    5. 5xx Server Error
      • The server failed to fulfill an apparently valid request.
HTTP Request & Response Example (1)

HTTP Response - Example Codes

  1. 1xx Information
    • 102 Processing:
      • Indicates that the server has received the request and is processing it, but the response is not yet available.
  2. 2xx Successful
    • 200 OK
      • Indicates that the request succeeded.
    • 201 Created
      • Indicates that the request succeeded and a new resource was created (ie. in response to POST)
  3. 3xx Redirection
    • 301 Moved Permanently
      • Permanently indicates that the requested resource has been moved, and the server indicates its new location.
  4. 4xx Client Error
    • 403 Unauthorized
      • Means the client must authenticate to get a response.
    • 404 Not Found
      • Means the requested resource was not found.
  5. 5xx Server Error
    • 500 Internal Server Error
      • Means the server encountered something unexpected that it doesn’t know how to handle.

REST

REST stands for Representational State Transfer.

  • REST APIs are also known as REST-based APIs OR RESTful APIs
  • REST isn’t a specific API. Instead, it describes a set of rules about how the API should work.

  • The six constraints of RESTful architecture are:
    1. Uniform Interface
    2. Client-server
    3. Stateless
    4. Cacheable or non-cacheable
    5. Layered system
    6. Code-on-demand

REST - Client-server

REST APIs use a client-server architecture.

  • The client uses API calls (HTTP Requests) to access the resources on the server.
  • The separation between the client and server means they can both change and evolve independently of each other.
    • Therefore, when the client application changes or the server application changes, the interface between them must NOT break.
HTTP Request & Response Example (2)

REST - Stateless

REST APIs exchanges are stateless

  • This means that each API exchange is a separate event, independent of all past exchanges between the client and server.
  • The server does not store information about previous requests from the client to determine how it should respond to new requests.
  • If authentication is required, this means that the client must authenticate with the server for each request it makes.
  • TCP is an example of a stateful protocol.
  • UDP is an example of a stateless protocol.

REST APIs and TCP - Stateful and Stateless

  • Although REST APIs use HTTP, which uses TCP (stateful) as its Layer 4 protocol, HTTP and REST APIs themselves aren’t stateful. The functions of each layer are separate.

REST - Cacheable or Non-Cacheable

REST APIs must support caching of data.

  • Caching refers to storing data for future use.
  • Not all resources have to be cacheable, but cacheable resources MUST be declared as cacheable.

Jeremy IT Lab előadás videó:

61. Nap - REST API (Day 61 - REST API)

Parancsok (Commands)

Nincsenek parancsok :)

REST API ismeretek (REST API Info)

Az API (Application Programming Interface) egy olyan szoftveres felület, amely lehetővé teszi két alkalmazás számára, hogy kommunikáljanak egymással.

  • Az API-k nemcsak a hálózati automatizációhoz elengedhetetlenek, hanem mindenféle más alkalmazáshoz is.
  • Az SDN architektúrában API-kat használnak az alkalmazások és az SDN Controller közötti kommunikációra (az NBI-n keresztül), valamint az SDN Controller és a hálózati eszközök között (az SBI-n keresztül).
  • Az NBI jellemzően REST API-kat használ.
  • A Netconf és a Restconf népszerű Southbound API-k.

CRUD

A CRUD (Create, Read, Update, Delete) azokra az alapműveletekre utal, amelyeket a REST API-k használatával hajtunk végre.

  1. Create (Létrehozás)
    • A Create műveletek új változók létrehozására és azok kezdeti értékeinek beállítására szolgálnak.
    • Példa: Az „ip_address” változó létrehozása és értékének beállítása erre: „10.1.1.1”.
  2. Read (Olvasás / Lekérés)
    • A Read műveletek egy változó értékének lekérésére szolgálnak.
    • Példa: Mi az „ip_address” változó értéke?
  3. Update (Módosítás / Frissítés)
    • Az Update műveletek egy változó értékének megváltoztatására szolgálnak.
    • Példa: Az „ip_address” változó értékének módosítása erre: „10.2.3.4”.
  4. Delete (Törlés)
    • A Delete műveletek változók törlésére szolgálnak.
    • Példa: Az „ip_address” változó törlése.

  • A HTTP igéket (verbs / methods) használ ezen CRUD műveletek leképezésére.
  • A REST API-k jellemzően HTTP-t használnak.
Cél (Purpose)CRUD MűveletHTTP Ige (Verb)
Új változó létrehozásaCreatePOST
Változó értékének lekéréseReadGET
Változó értékének módosításaUpdatePUT, PATCH
Változó törléseDeleteDELETE

HTTP Request (HTTP Kérés)

Amikor egy HTTP kliens kérést küld egy HTTP szervernek, a HTTP fejléc (header) ilyen információkat tartalmaz:

  • Egy HTTP igét (Verb, pl. GET).
  • Egy URI-t (Uniform Resource Identifier), amely meghatározza az elérni kívánt erőforrást.
Példa HTTP Request-re
  • Egy URI három különböző részből áll:
    1. Scheme (Séma / Protokoll)
    2. Authority (Szerver / Hoszt)
    3. Paths (Elérési útvonal)
  • Példa: https://sandboxdnac.cisco.com/dna/intent/api/v1/network-device
    • Scheme: https
    • Authority: sandboxdnac.cisco.com
    • Paths: dna/intent/api/v1/network-device

HTTP Request - Fejlécek (Headers)

  • A HTTP request további fejléceket (headers) is tartalmazhat, amelyek extra információkat adnak át a szervernek.
Példa extra fejlécekkel ellátott HTTP Request-re
  • Példa erre az Accept fejléc, amely tájékoztatja a szervert arról, hogy milyen típusú adatokat képes a kliens fogadni válaszként.
  • Amikor egy REST kliens API hívást (kérést) intéz egy REST szerverhez, a fentihez hasonló HTTP requestet küld.
  • A REST API-knak nem feltétlenül kell kifejezetten HTTP-t használniuk a kommunikációhoz, habár a HTTP a legelterjedtebb választás.

HTTP Response (HTTP Válasz)

  • A szerver válasza tartalmaz egy állapotkódot (status code), amely jelzi a kérés sikerességét vagy sikertelenségét, valamint egyéb részleteket.
  • Az első számjegy a válasz kategóriáját (osztályát) jelöli:
    1. 1xx Informational (Információs)
      • A kérés beérkezett, a folyamat folytatódik.
    2. 2xx Successful (Sikeres)
      • A kérést a szerver sikeresen fogadta, megértette és elfogadta.
    3. 3xx Redirection (Átirányítás)
      • További műveletre van szükség a kérés teljesítéséhez.
    4. 4xx Client Error (Klienshiba)
      • A kérés hibás szintaxist tartalmaz, vagy nem teljesíthető.
    5. 5xx Server Error (Szerverhiba)
      • A szerver nem tudott teljesíteni egy látszólag érvényes kérést.
Példa HTTP Requestre és Response-ra (1)

HTTP Response - Példakódok (HTTP Response - Example Codes)

  1. 1xx Information
    • 102 Processing:
      • Azt jelzi, hogy a szerver megkapta a kérést és dolgozik rajta, de a válasz még nem áll rendelkezésre.
  2. 2xx Successful
    • 200 OK
      • Azt jelzi, hogy a kérés sikeres volt.
    • 201 Created
      • Azt jelzi, hogy a kérés sikeres volt, és új erőforrás jött létre (pl. egy POST kérésre adott válaszként).
  3. 3xx Redirection
    • 301 Moved Permanently
      • Azt jelzi, hogy a kért erőforrás véglegesen elköltözött, és a szerver megadja annak új helyét.
  4. 4xx Client Error
    • 403 Unauthorized (vagy Forbidden)
      • Azt jelenti, hogy a kliensnek hitelesítenie kell magát a válasz megszerzéséhez.
    • 404 Not Found
      • Azt jelenti, hogy a kért erőforrás nem található.
  5. 5xx Server Error
    • 500 Internal Server Error
      • Azt jelenti, hogy a szerver váratlan hibába ütközött, amelyet nem tud kezelni.

REST

A REST a Representational State Transfer rövidítése.

  • A REST API-kat REST-based API-kként VAGY RESTful API-kként is ismerik.
  • A REST nem egy konkrét API, hanem olyan szabályok összessége, amelyek meghatározzák, hogyan kell az API-nak működnie.

  • A RESTful architektúra hat alapvető megkötése (constraints):
    1. Uniform Interface (Egységes felület)
    2. Client-server (Kliens-szerver modell)
    3. Stateless (Állapotmentesség)
    4. Cacheable or non-cacheable (Gyorsítótárazható vagy nem gyorsítótárazható)
    5. Layered system (Rétegzett rendszer)
    6. Code-on-demand (Igény szerinti kód - opcionális)

REST - Kliens-szerver (Client-server)

A REST API-k client-server architektúrát használnak.

  • A kliens API hívásokat (HTTP Request-eket) használ a szerveren lévő erőforrások eléréséhez.
  • A kliens és szerver szétválasztása biztosítja, hogy mindkettő egymástól függetlenül módosulhasson és fejlődhessen.
    • Ezért a kliensalkalmazás vagy a szerveralkalmazás módosulásakor a köztük lévő interfész NEM törhet el.
Példa HTTP Requestre és Response-ra (2)

REST - Állapotmentesség (Stateless)

A REST API adatcserék állapotmentesek (stateless).

  • Ez azt jelenti, hogy minden API tranzakció egy különálló esemény, amely független a kliens és a szerver közötti korábbi adatcseréktől.
  • A szerver nem tárol információkat a kliens korábbi kéréseiről annak eldöntésére, hogyan válaszoljon az új kérésekre.
  • Ha hitelesítés (authentication) szükséges, a kliensnek minden egyes elküldött kérésével hitelesítenie kell magát a szervernél.
  • A TCP egy állapotmegőrző (stateful) protokoll.
  • Az UDP egy állapotmentes (stateless) protokoll.

REST API-k és a TCP - Stateful és Stateless

  • Habár a REST API-k a HTTP-t használják, amely a TCP-t (stateful) alkalmazza Layer 4 protokollként, maga a HTTP és a REST API-k nem állapotmegőrzők (nem stateful-ok). Az egyes rétegek funkciói elkülönülnek egymástól.

REST - Gyorsítótárazható vagy Nem gyorsítótárazható (Cacheable or Non-Cacheable)

A REST API-knak támogatniuk kell az adatok gyorsítótárazását (caching).

  • A caching az adatok későbbi felhasználás céljából történő tárolására utal.
  • Nem kell minden erőforrásnak gyorsítótárazhatónak lennie, de a gyorsítótárazható (cacheable) erőforrásokat KÖTELEZŐ akként deklarálni.

Graph View