OpenAPI
OpenAPI (OpenAPI Specification, OAS) adalah standar terbuka untuk mendeskripsikan API HTTP dalam format yang bisa dibaca mesin: path dan metode apa yang dimiliki sebuah layanan, parameter apa yang diterimanya, apa yang dikembalikannya, dan cara mengirim key. Dokumennya ditulis dalam JSON atau YAML, sehingga manusia maupun program dapat memahami API tanpa akses ke kode sumbernya.
Asal-usul standar ini
Standar ini berkembang dari Swagger Specification yang pertama kali dirilis pada 2011. Pada 2015, Swagger 2.0 disumbangkan ke OpenAPI Initiative, proyek terbuka di bawah Linux Foundation, dan sejak 2016 spesifikasinya dikembangkan sebagai OpenAPI. Versi 3.0 terbit pada 2017 dan 3.1 pada Februari 2021; lini terbarunya adalah 3.2 (spesifikasi 3.1).
Apa yang dideskripsikan dokumen ini
servers— URL dasar API;paths— path dan metode: setiap operasi punyaoperationIdsendiri,summarysingkat, parameter beserta lokasinya (in: query, path, header), dan respons per kode status;components.schemas— skema objek (di 3.1 berbasis JSON Schema 2020-12);components.securitySchemes— autentikasi, misalnya key di header:type: apiKey,in: header.
Kutipan singkat dari spesifikasi Genesis API, yaitu operasi funding rate dan skema key:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/funding/rates": {
"get": {
"operationId": "getFundingRates",
"summary": "Funding rates",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query", "required": false,
"schema": { "type": "string" } }
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": { "type": "apiKey", "in": "header",
"name": "X-API-Key" }
}
}
}
Field berawalan x- adalah ekstensi spesifikasi: x-genesis-plans mencantumkan paket yang menyertakan operasi tersebut.
Untuk apa spesifikasi dipakai
Standar ini menyebut beberapa kegunaan, di antaranya membuat dokumentasi, membuat klien dan server dalam berbagai bahasa, serta pengujian. Bagi agen AI, spesifikasi adalah perangkat alat siap pakai: operasi dengan operationId, deskripsi, dan skema parameter dapat dipetakan menjadi tool untuk function calling atau server MCP.
OpenAPI di Genesis API
Spesifikasi Genesis API ada di genesisarbitrage.com/openapi.json: OpenAPI 3.1, 37 operasi, key di header X-API-Key (autentikasi). Spesifikasi ini juga bisa ditemukan secara otomatis: file /.well-known/api-catalog di genesisarbitrage.com, yang didefinisikan oleh RFC 9727, menunjuk ke sana lewat tautan service-desc. Cara menghubungkan spesifikasi ke agen dibahas di Genesis API untuk agen AI.
Lihat juga: REST API, JSON, API endpoint, data pasar kripto untuk agen AI.
Tanya jawab
Apakah Swagger dan OpenAPI sama?
Keduanya satu standar dengan dua nama: Swagger Specification dikembangkan sebagai OpenAPI sejak 2016. Versi 2.0 masih dirilis sebagai Swagger 2.0, dan mulai 3.0 diterbitkan sebagai OpenAPI Specification.
Apakah saya butuh SDK jika sudah ada spesifikasi?
Untuk Genesis API tidak: setiap permintaan adalah GET dengan satu header, jadi klien HTTP apa pun bisa dipakai. Membuat klien dari spesifikasi masuk akal jika Anda ingin metode bertipe.