Geekly articles weekly

Otomasi Untuk Yang Terkecil. Catatan. API tenang

Artikel ini adalah salah satu dari catatan singkat yang dijanjikan selama serangkaian artikel Automation For The Smallest .
Karena cara utama untuk berinteraksi dengan sistem IPAM adalah RESTful API, saya memutuskan untuk membicarakannya secara terpisah.


Saya memuji arsitek dunia modern - kami memiliki antarmuka standar. Ya, ada banyak dari mereka - ini adalah minus, tetapi mereka - ini adalah plus.

Antarmuka ini telah mendapatkan nama API - Antarmuka Pemrograman Aplikasi.

Salah satu antarmuka ini adalah RESTful API, yang digunakan untuk bekerja dengan NetBox.



Jika ini sangat sederhana, maka API memberi klien satu set alat untuk mengelola server. Dan klien pada dasarnya bisa apa saja: browser web, konsol perintah, aplikasi yang dikembangkan oleh pabrikan, atau aplikasi lain yang memiliki akses ke API.

Misalnya, dalam kasus NetBox, Anda dapat menambahkan perangkat baru dengan cara berikut: melalui browser web, mengirim curl'om permintaan di konsol, menggunakan Postman, mengakses perpustakaan permintaan dengan python, menggunakan SDK kotak pynetbox atau pergi ke Swagger.

Jadi, setelah menulis satu antarmuka, pabrikan selamanya membebaskan diri dari kebutuhan untuk setuju dengan setiap klien baru bagaimana menghubungkannya (meskipun ini hanya sedikit licik).

Isi


  • SISA, TENANG, API
  • Struktur pesan HTTP
    • Mulai baris
    • Pos
    • Isi pesan HTTP

  • Metode
    • HTTP DAPATKAN
    • HTTP POST
    • PUT HTTP
    • HTTP PATCH
    • HAPUS HTTP

  • Cara untuk bekerja dengan API RESTful
    • Keriting
    • Tukang pos
    • Python + Permintaan
    • Pynebtbox SDK
    • Kesombongan

  • Kritik REST dan alternatif
  • Tautan yang bermanfaat

SISA, TENANG, API


Di bawah ini saya akan memberikan deskripsi yang sangat sederhana tentang apa itu REST.

Untuk memulainya, RESTful API adalah antarmuka interaksi berbasis REST, sedangkan REST ( REpresentational State Transfer ) sendiri adalah seperangkat batasan yang digunakan untuk membuat layanan WEB.

Dimungkinkan untuk membaca tentang batasan apa yang dapat ditemukan dalam Bab 5 disertasi Roy Fielding, Gaya Arsitektur dan Desain Arsitektur Perangkat Lunak Berbasis Jaringan . Biarkan saya memberi Anda hanya tiga yang paling signifikan (dari sudut pandang saya) dari mereka:

  1. Arsitektur REST menggunakan model interaksi Client-Server.
  2. Setiap permintaan REST berisi semua informasi yang diperlukan untuk pelaksanaannya. Artinya, server tidak boleh mengingat apa pun tentang permintaan klien sebelumnya, yang, seperti yang Anda ketahui, dicirikan oleh kata Stateless - kami tidak menyimpan informasi status.
  3. Antarmuka terpadu. Implementasi aplikasi terpisah dari layanan yang disediakannya. Artinya, pengguna tahu apa yang dilakukannya dan bagaimana berinteraksi dengannya, tetapi bagaimana itu tidak masalah. Saat Anda mengubah aplikasi, antarmuka tetap sama, dan klien tidak perlu menyesuaikan.

Layanan WEB yang memenuhi semua prinsip REST disebut layanan WEB RESTful .

Dan API yang menyediakan layanan WEB RESTful disebut API RESTful.

REST bukan protokol, tetapi yang disebut gaya arsitektur (salah satunya). Dikembangkan dengan HTTP oleh Roy Fielding, REST dimaksudkan untuk menggunakan HTTP 1.1 sebagai transportasi.

Alamat tujuan (atau dengan kata lain - sebuah objek, atau dengan cara lain - titik akhir) - ini adalah URI kita yang biasa.

Format data yang dikirim adalah XML atau JSON .
Untuk seri artikel tentang linkmeup ini, penyebaran read-only telah dikerahkan (untuk Anda, pembaca yang budiman). Instalasi NetBox : netbox.linkmeup.ru : 45127.

Hak baca tidak diperlukan, tetapi jika Anda ingin mencoba membaca dengan token, Anda dapat menggunakan ini: Token API: 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8 .
Mari buat satu permintaan untuk bersenang-senang:

curl -X GET -H "Authorization: TOKEN 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8" \ -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/1/

Yaitu, dengan utilitas curl , kami membuat objek GET di netbox.linkmeup.ru : 45127 / api / dcim / devices / 1 / dengan respons JSON dan lekukan 4 spasi.

Atau sedikit lebih akademis: GET mengembalikan objek perangkat yang diketik, yang merupakan parameter dari objek DCIM .

Anda juga dapat memenuhi permintaan ini - cukup salin ke terminal Anda.
URL yang kami maksudkan dalam permintaan disebut Endpoint . Dalam arti tertentu, ini adalah objek terakhir yang dengannya kita akan berinteraksi.
Misalnya, dalam hal netbox, daftar semua titik akhir dapat diperoleh di sini .
Dan perhatikan tanda / di akhir URL - itu diperlukan .
Inilah yang kami dapatkan sebagai tanggapan:

 { "id": 1, "name": "mlg-host-0", "display_name": "mlg-host-0", "device_type": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/device-types/4/", "manufacturer": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/manufacturers/4/", "name": "Hypermacro", "slug": "hypermacro" }, "model": "Server", "slug": "server", "display_name": "Hypermacro Server" }, "device_role": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/device-roles/1/", "name": "Server", "slug": "server" }, "tenant": null, "platform": null, "serial": "", "asset_tag": null, "site": { "id": 6, "url": "http://netbox.linkmeup.ru/api/dcim/sites/6/", "name": "", "slug": "mlg" }, "rack": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/racks/1/", "name": "A", "display_name": "A" }, "position": 41, "face": { "value": "front", "label": "Front", "id": 0 }, "parent_device": null, "status": { "value": "active", "label": "Active", "id": 1 }, "primary_ip": null, "primary_ip4": null, "primary_ip6": null, "cluster": null, "virtual_chassis": null, "vc_position": null, "vc_priority": null, "comments": "", "local_context_data": null, "tags": [], "custom_fields": {}, "config_context": {}, "created": "2020-01-14", "last_updated": "2020-01-14T18:39:01.288081Z" }

Ini adalah JSON (seperti yang kami minta), menggambarkan perangkat dengan ID 1: apa yang dipanggil, dengan peran apa, model apa, di mana tempatnya, dll.

Ini akan terlihat seperti permintaan HTTP:

  GET /api/dcim/devices/1/ HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4


Jadi jawabannya akan terlihat:
  HTTP/1.1 200 OK Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive Data

Buang transaksi .

Sekarang mari kita mencari tahu apa yang telah kita lakukan.


Struktur pesan HTTP


Pesan HTTP terdiri dari tiga bagian, hanya yang pertama diperlukan.

  • Mulai baris
  • Pos
  • Badan pesan

Mulai baris


Baris awal permintaan dan respons HTTP terlihat berbeda.

Permintaan HTTP


 METHOD URI HTTP_VERSION

Metode menentukan tindakan apa yang ingin dilakukan klien: menerima data, membuat objek, memperbaruinya, menghapusnya.
URI - pengidentifikasi sumber daya tempat klien mengakses atau dengan kata lain, jalur ke sumber daya / dokumen.
HTTP_VERSION adalah versi HTTP, masing-masing. Hari ini, untuk REST, selalu 1.1.
Contoh:

 GET /api/dcim/devices/1/ HTTP/1.1


Tanggapan HTTP


 HTTP_VERSION STATUS_CODE REASON_PHRASE

HTTP_VERSION - Versi HTTP (1.1).
STATUS_CODE - tiga digit kode status (200, 404, 502, dll.)
REASON_PHRASE - Penjelasan (OK, BUKAN DITEMUKAN, BUR GATEWAY, dll.)

Contoh:

 HTTP/1.1 200 OK

Pos


Header meneruskan parameter untuk transaksi HTTP ini.

Misalnya, dalam contoh di atas dalam permintaan HTTP, ini adalah:

  Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4

Mereka menunjukkan itu

  1. Kami beralih ke host netbox.linkmeup.ru:45127 ,
  2. Permintaan dihasilkan dalam ikal ,
  3. Dan kami menerima data dalam format JSON dengan lekukan 4 .

Dan inilah tajuk dalam respons HTTP:

  Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive

Mereka menunjukkan itu

  1. Jenis Server: nginx di Ubuntu ,
  2. Waktu respon
  3. Format data respons: JSON
  4. Panjang data respons: 1638 byte
  5. Koneksi tidak perlu ditutup - masih akan ada data.

Header, seperti yang telah Anda perhatikan, terlihat seperti nama: pasangan nilai, dipisahkan oleh tanda ":".

Daftar lengkap kemungkinan tajuk .

Isi pesan HTTP


Tubuh digunakan untuk mentransfer data aktual.

Dalam respons HTTP, ini bisa berupa laman HTML, atau dalam kasus kami objek JSON.

Harus ada setidaknya satu garis kosong antara header dan tubuh.

Saat menggunakan metode GET dalam permintaan HTTP, biasanya tidak ada badan karena tidak ada yang dikirim. Tetapi tubuh berada dalam respons HTTP.

Tetapi misalnya, dengan POST, tubuh akan sudah ada dalam permintaan. Mari kita bicara tentang metode dan bicara sekarang.


Metode


Seperti yang sudah Anda pahami, HTTP menggunakan metode untuk bekerja dengan layanan WEB. Hal yang sama berlaku untuk RESTful API.

Skenario kehidupan nyata yang mungkin dijelaskan dengan istilah CRUD - Buat, Baca, Perbarui, Hapus .
Berikut adalah daftar metode HTTP paling populer yang menerapkan CRUD:

  • HTTP DAPATKAN
  • HTTP POST
  • PUT HTTP
  • HAPUS HTTP
  • HTTP PATCH

Metode juga disebut kata kerja , karena mereka menunjukkan tindakan apa yang dilakukan.

Daftar lengkap metode .

Mari kita lihat masing-masing dari mereka menggunakan contoh NetBox.

HTTP DAPATKAN


Ini adalah metode untuk mendapatkan informasi.

Jadi, misalnya, kami menghapus daftar perangkat:

 curl -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/

Metode GET aman karena tidak mengubah data, tetapi hanya meminta.

Itu idempoten dari sudut pandang bahwa permintaan yang sama selalu mengembalikan hasil yang sama (sampai data itu sendiri telah berubah).

Pada GET, server mengembalikan pesan dengan kode HTTP dan badan respons ( kode respons dan badan respons ).

Yaitu, jika semuanya OK, maka kode responsnya adalah 200 (OK).
Jika URL tidak ditemukan, 404 (TIDAK DITEMUKAN).
Jika ada sesuatu yang salah dengan server atau komponen itu sendiri, itu bisa 500 (SERVER ERROR) atau 502 (BAD GATEWAY).
Semua kode respons yang memungkinkan .

Tubuh dikembalikan dalam format JSON atau XML.

Buang transaksi .

Mari kita beri beberapa contoh lagi. Sekarang kami akan meminta informasi pada perangkat tertentu dengan namanya.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0"

Di sini, untuk mengatur kondisi pencarian di URI, saya juga menentukan atribut objek (parameter nama dan nilainya mlg-leaf-0 ). Seperti yang Anda lihat, sebelum kondisi dan setelah slash ada tanda "?" , dan nama serta nilai dipisahkan oleh tanda "=" .

Seperti inilah bentuk permintaannya.

  GET /api/dcim/devices/?name=mlg-leaf-0 HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4

Buang transaksi .

Jika Anda perlu menentukan beberapa kondisi, maka kueri akan terlihat seperti ini:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?role=leaf&site=mlg"

Di sini kami meminta semua perangkat daun yang ada di situs web mlg .
Yaitu, kedua kondisi dipisahkan satu sama lain oleh tanda "&" .

Buang transaksi .

Dari yang penasaran dan menyenangkan - jika melalui "&" Anda menetapkan dua kondisi dengan nama yang sama, maka di antara mereka sebenarnya tidak akan ada "DAN" yang logis, tetapi "ATAU" yang logis.

Artinya, permintaan seperti itu sebenarnya akan mengembalikan dua objek: mlg-leaf-0 dan mlg-spine-0

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0&name=mlg-spine-0"

Buang transaksi .

Mari kita coba mengakses URL yang tidak ada.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/IDGAF/"

Buang transaksi .


HTTP POST


POST digunakan untuk membuat objek baru dalam kumpulan objek. Atau dalam bahasa yang lebih kompleks: untuk membuat sumber daya bawahan baru.

Klarifikasi dari arthuriantech :
Termasuk, tetapi tidak terbatas pada. Metode POST dirancang untuk mentransfer data ke server untuk diproses lebih lanjut - metode ini digunakan untuk tindakan apa pun yang tidak perlu distandarisasi dalam HTTP. Sebelum RFC 5789, itu adalah satu-satunya cara hukum untuk melakukan perubahan parsial.
roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
tools.ietf.org/html/rfc7231#s-4-4.3


Artinya, jika ada satu set perangkat, maka POST memungkinkan Anda untuk membuat objek perangkat baru di dalam perangkat.

Pilih Endpoint yang sama dan gunakan POST untuk membuat perangkat baru.

 curl -X POST "http://netbox.linkmeup.ru:45127/api/dcim/devices/" \ -H "accept: application/json"\ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\"}"

Header Otorisasi sudah muncul di sini, berisi token yang mengesahkan permintaan tulis, dan setelah direktif -d ada JSON dengan parameter perangkat yang dibuat:

 { "name": "just a simple russian girl", "device_type": 1, "device_role": 1, "site": 3, "rack": 3, "position": 5, "face": "front"}

Permintaan Anda tidak akan berfungsi, karena Token tidak lagi valid - jangan mencoba menulis ke NetBox.
Responsnya datang dengan respons HTTP dengan kode 201 (CREATED) dan JSON di badan pesan, di mana server mengembalikan semua parameter tentang perangkat yang dibuat.

  HTTP/1.1 201 Created Server: nginx/1.14.0 (Ubuntu) Date: Sat, 18 Jan 2020 11:00:22 GMT Content-Type: application/json Content-Length: 1123 Connection: keep-alive JSON

Buang transaksi .

Sekarang, dengan permintaan baru dengan metode GET, Anda dapat melihatnya di output:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?q=russian"

"Q" di NetBox memungkinkan Anda untuk menemukan semua objek yang berisi nama mereka sebuah garis yang melangkah lebih jauh.
POST, jelas, tidak aman atau idempoten - itu mungkin mengubah data, dan permintaan yang dieksekusi ganda akan mengarah pada penciptaan objek yang sama kedua, atau kesalahan.


PUT HTTP


Ini adalah metode untuk memodifikasi objek yang ada. Titik akhir untuk PUT terlihat berbeda dari untuk POST - sekarang berisi objek tertentu.

PUT dapat mengembalikan kode 201 atau 200.

Poin penting dengan metode ini: Anda harus melewati semua atribut yang diperlukan, karena PUT menggantikan objek lama.

Karenanya, jika, misalnya, hanya mencoba menambahkan atribut asset_tag ke perangkat baru kami, kami mendapatkan kesalahan:

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"asset_tag\": \"12345678\"}" 

 {"device_type":["This field is required."],"device_role":["This field is required."],"site":["This field is required."]}

Tetapi jika Anda menambahkan bidang yang hilang, maka semuanya akan berfungsi:

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\", \"asset_tag\": \"12345678\"}"

Buang transaksi .
Perhatikan URL di sini - sekarang termasuk ID perangkat yang ingin kita ubah ( 18 ).


HTTP PATCH


Metode ini digunakan untuk memodifikasi sebagian sumber daya.
Wat? Anda bertanya, tetapi bagaimana dengan PUT?

PUT adalah metode yang awalnya ada dalam standar, yang melibatkan penggantian lengkap objek yang bisa berubah. Dengan demikian, dalam metode PUT, seperti yang saya tulis di atas, Anda harus menentukan bahkan atribut dari objek yang tidak berubah.

Dan PATCH ditambahkan kemudian dan memungkinkan Anda untuk menentukan hanya atribut yang benar-benar berubah.

Sebagai contoh:

 curl -X PATCH "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"serial\": \"BREAKINGBAD\"}"

Di sini, ID perangkat juga ditentukan dalam URL, tetapi hanya ada satu atribut serial untuk diubah.

Buang transaksi .


HAPUS HTTP


Jelas menghapus objek.

Sebuah contoh

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f"

Metode DELETE idempoten dari sudut pandang bahwa kueri yang diulang tidak lagi mengubah apa pun dalam daftar sumber daya (tetapi akan mengembalikan kode 404 (TIDAK DITEMUKAN).

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" 

 {"detail":"Not found."}


Cara untuk bekerja dengan API RESTful


Curl, tentu saja, sangat nyaman untuk prajurit CLI yang gagah berani, tetapi ada alat yang lebih baik.

Tukang pos


Tukang pos memungkinkan Anda untuk membentuk kueri di antarmuka grafis dengan memilih metode, header, tubuh, dan menampilkan hasilnya dalam bentuk yang dapat dibaca manusia.

Selain itu, kueri dan URI dapat disimpan dan dikembalikan lagi nanti.

Unduh Postman di situs web resmi .

Jadi kita bisa melakukan GET:


Di sini Token ditunjukkan dalam GET sebagai contoh saja.

Dan begitu POST:



Tukang pos hanya untuk digunakan dengan API tenang.
Sebagai contoh, jangan mencoba mengirim NETCONF XML melalui itu, seperti yang saya lakukan pada awal karir otomasi saya.
Salah satu bonus bagus dari API yang ditentukan adalah Anda dapat mengimpor semua titik akhir dan metode mereka ke tukang pos sebagai koleksi.

Untuk melakukan ini, di jendela Impor (File-> Impor), pilih Impor Dari Tautan dan tempel di jendela netbox.linkmeup.ru URL: 45127 / api / docs /? Format = openapi.



Selanjutnya, semua yang Anda dapat dapat ditemukan di koleksi.





Permintaan Python +


Tetapi bahkan melalui Postman, Anda kemungkinan besar tidak akan mengelola sistem Produksi Anda. Tentunya, Anda akan memiliki aplikasi eksternal yang ingin berinteraksi dengannya tanpa partisipasi Anda.

Misalnya, sistem pembuatan konfigurasi ingin mengambil daftar antarmuka IP dari NetBox.
Python memiliki pustaka permintaan yang indah yang mengimplementasikan pekerjaan melalui HTTP.
Contoh meminta daftar semua perangkat:

 import requests HEADERS = {'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" devices = requests.get(request_url, headers = HEADERS) print(devices.json())

Tambahkan perangkat baru lagi:

 import requests API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" HEADERS = {'Authorization': f'Token {API_TOKEN}', 'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" device_parameters = { "name": "just a simple REQUESTS girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = requests.post(request_url, headers = HEADERS, json=device_parameters) print(new_device.json())


Python + NetBox SDK


Dalam kasus NetBox, ada juga Python SDK - Pynetbox , yang mewakili semua NetBox Endpoints sebagai objek dan atributnya, melakukan semua pekerjaan kotor untuk Anda menghasilkan URI dan mem-parsing respons, walaupun tentu saja tidak gratis.

Misalnya, mari kita lakukan hal yang sama seperti di atas, menggunakan kotak pesan.
Daftar semua perangkat:

 import pynetbox NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL) devices = nb.dcim.devices.all() print(devices)

Tambahkan perangkat baru:

 import pynetbox API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL, token = API_TOKEN) device_parameters = { "name": "just a simple PYNETBOX girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = nb.dcim.devices.create(**device_parameters) print(new_device)

Dokumentasi Pynetbox


Kesombongan


Apa lagi yang layak berkat dekade terakhir adalah spesifikasi API. Jika Anda mengikuti jalur ini , Anda akan dibawa ke dokumentasi Swagger UI - Netbox API.



Halaman ini mencantumkan semua Titik Akhir, metode untuk mengatasinya, kemungkinan parameter dan atribut, serta menunjukkan mana dari mereka yang diperlukan. Selain itu, jawaban yang diharapkan dijelaskan.



Pada halaman yang sama, Anda dapat melakukan kueri interaktif dengan mengklik Coba ini .
Untuk beberapa alasan, kesombongan mengambil nama server tanpa port sebagai URL Basis, jadi fungsi Coba saja tidak berfungsi dalam contoh kesombongan saya. Tetapi Anda dapat mencobanya di instalasi Anda sendiri.
Ketika Anda mengklik Execute Swagger, UI akan menghasilkan string ikal yang dapat digunakan untuk membuat permintaan serupa dari baris perintah.

Di Swagger UI, Anda bahkan dapat membuat objek:



Untuk melakukan ini, cukup menjadi pengguna resmi dengan hak yang diperlukan.

Apa yang kita lihat di halaman ini adalah Swagger UI, sebuah dokumentasi yang dihasilkan berdasarkan spesifikasi API.

Dengan tren dalam arsitektur layanan mikro, menjadi semakin penting untuk memiliki API standar untuk interaksi antara komponen, titik akhir dan metode yang mudah ditentukan untuk orang dan aplikasi tanpa mencari-cari melalui kode sumber atau dokumentasi PDF.

Oleh karena itu, pengembang saat ini semakin mengikuti paradigma API Pertama ketika mereka pertama kali berpikir tentang API, dan baru kemudian tentang implementasinya.
API pertama kali ditentukan dalam desain ini, dan kemudian dokumentasi, aplikasi klien, bagian server dihasilkan darinya, dan tes diperlukan.

Swagger adalah bahasa kerangka kerja dan spesifikasi (yang sekarang telah diubah namanya menjadi OpenAPI 2.0), memungkinkan Anda untuk mengimplementasikan tugas ini.
Aku tidak akan terlalu jauh ke dalamnya.

Untuk detail lebih lanjut di sini:



Kritik REST dan alternatif


Ada satu, ya. Tidak semua yang ada di dunia tahun 2000 itu sangat cerah.

Bukan sebagai seorang ahli, saya tidak berani mengungkapkan masalah ini secara substansial, tetapi saya akan memberikan tautan ke artikel yang tak terbantahkan tentang Habré .

Antarmuka alternatif untuk interaksi komponen sistem saat ini adalah gRPC. Dia juga menubuatkan masa depan yang hebat di bidang pendekatan baru untuk bekerja dengan peralatan jaringan. Tapi kita akan membicarakannya di masa depan, ketika gilirannya tiba.

Anda juga dapat melihat GraphQL yang menjanjikan, tetapi sekali lagi kami tidak perlu bekerja dengannya untuk saat ini, jadi tetap untuk studi independen.


Itu penting
Token a9aae70d65c928a554f9a038b9d4703a1583594f digunakan untuk tujuan demonstrasi saja dan tidak berfungsi lagi.

Indikasi langsung token dalam kode program tidak dapat diterima dan saya buat di sini hanya untuk menyederhanakan contoh.


Tautan yang bermanfaat



Terima kasih


  • Andrei Panfilov untuk proofreading dan editing
  • Alexander Fatin untuk proofreading dan editing

Source: https://habr.com/ru/post/id485618/

More articles:


All Articles