Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Lihat dokumentasi
Apigee Edge.
Pada fase Desain, Anda menentukan persyaratan untuk API Anda. Sebagai desainer API, Anda merencanakan layanan yang ingin diekspos ke konsumen, dan mendesain API untuk mengakses layanan tersebut. Anda membuat salah satu dokumen berikut untuk mencatat persyaratan API Anda:
- Dokumen OpenAPI
- Skema GraphQL
Bagian berikut memberikan informasi selengkapnya tentang dokumen OpenAPI dan GraphQL serta peran yang dimainkannya dalam siklus proses API Anda. Untuk perbandingan kedua opsi desain API, lihat perbandingan REST dan GraphQL dalam postingan blog ini.
Apa itu Spesifikasi OpenAPI?
"OpenAPI Initiative (OAI) berfokus pada pembuatan, pengembangan, dan promosi Format Deskripsi API netral vendor berdasarkan Spesifikasi Swagger." Untuk mengetahui informasi selengkapnya tentang Inisiatif OpenAPI, lihat https://openapis.org.
Dokumen OpenAPI menggunakan format standar untuk mendeskripsikan RESTful API. Ditulis dalam format JSON atau YAML, dokumen OpenAPI dapat dibaca mesin, tetapi juga mudah dibaca dan dipahami oleh manusia. Spesifikasi OpenAPI memungkinkan deskripsi formal elemen API seperti jalur dasar, jalur dan kata kerja, header, parameter kueri, jenis konten, model respons, dan lainnya. Selain itu, dokumen OpenAPI biasanya digunakan untuk membuat dokumentasi API.
Berikut adalah fragmen dari dokumen OpenAPI yang menjelaskan contoh hello world sederhana Apigee. Untuk mengetahui informasi selengkapnya, lihat Spesifikasi OpenAPI di GitHub.
openapi: 3.0.0
info:
description: OpenAPI Specification for the Apigee mock target service endpoint.
version: 1.0.0
title: Mock Target API
paths:
/:
get:
summary: View personalized greeting
operationId: View a personalized greeting
description: View a personalized greeting for the specified or guest user.
parameters:
- name: user
in: query
description: Your user name.
required: false
schema:
type: string
responses:
"200":
description: Success
/help:
get:
summary: Get help
operationId: Get help
description: View help information about available resources in HTML format.
responses:
"200":
description: Success
...
Ada banyak sumber informasi yang sangat baik tentang Spesifikasi OpenAPI. Tempat yang tepat untuk memulai adalah situs OpenAPI Initiative, tempat Anda akan menemukan ringkasan, blog, dan link ke Spesifikasi OpenAPI. Lihat Spesifikasi untuk mengetahui deskripsi mendetail tentang elemen skema dan jenis data.
Ada sejumlah dokumen OpenAPI contoh JSON dan YAML yang dapat Anda download dari repositori Spesifikasi OpenAPI.
Apa itu skema GraphQL?
Skema GraphQL menjelaskan data yang tersedia di API Anda untuk dikueri oleh klien.
Manfaat menggunakan GraphQL meliputi:
- Satu endpoint memberikan akses ke semua kolom untuk operasi tertentu
- Bahasa kueri yang canggih, yang disebut Schema Definition Language, memungkinkan Anda mengakses data yang Anda butuhkan secara tepat, sehingga mencegah pengambilan data yang berlebihan atau kurang
- Pemrosesan kueri terjadi secara paralel
Untuk mengetahui informasi selengkapnya tentang GraphQL, lihat graphql.org.
Berikut adalah contoh skema GraphQL yang menentukan titik entri data (jenis Kueri), operasi tulis yang tersedia (jenis Mutasi), dan jenis data.
type Query {
Greeting: String
students: [Student]
}
type Mutation {
createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
newStudent: Student!
}
type Student {
Id: ID!
firstName: String!
lastName: String!
password: String!
collegeId: String!
}
Anda dapat membuat kueri skema GraphQL untuk menampilkan data persis yang Anda butuhkan sebagai payload JSON.
Apa yang terjadi jika saya mengubah dokumen?
Setiap dokumen OpenAPI atau GraphQL berfungsi sebagai sumber tepercaya di seluruh siklus proses API. Dokumen yang sama digunakan di setiap fase dalam siklus proses API, mulai dari pengembangan hingga publikasi dan pemantauan.
Saat Anda mengedit atau menghapus dokumen, tindakan ini akan berdampak pada dokumen tersebut:
- Jika Anda mengedit dokumen, Anda harus mengedit artefak terkait secara manual, termasuk proxy API dan produk API apa pun yang mengekspos sumber dayanya, serta membuat ulang dokumentasi referensi API untuk mencerminkan perubahan yang diterapkan dalam dokumen.
- Jika Anda menghapus dokumen, Anda harus menghapus artefak terkait secara manual, termasuk proxy API, dan mengedit produk API apa pun untuk menghapus resource terkait, serta membuat ulang dokumentasi referensi API untuk mencerminkan penghapusan dokumen dan resourcenya.
Apa yang terjadi saat saya membuat proxy API dari dokumen OpenAPI?
Anda dapat membuat proxy API dari dokumen OpenAPI. Hanya dalam beberapa klik, Anda akan memiliki proxy API dengan jalur, parameter, alur bersyarat, dan endpoint target yang dibuat secara otomatis. Kemudian, Anda dapat menambahkan fitur seperti keamanan OAuth, pembatasan kapasitas, dan caching.
Anda dapat membuat proxy API dari dokumen OpenAPI menggunakan Wizard Buat Proxy, seperti yang dijelaskan dalam Menggunakan Spesifikasi OpenAPI untuk membuat proxy. Untuk mendapatkan pengalaman langsung, ikuti tutorial Membuat proxy API dari Spesifikasi OpenAPI.
Saat memublikasikan API, Anda mengambil snapshot dokumen OpenAPI untuk membuat dokumentasi referensi API. Snapshot tersebut merepresentasikan revisi tertentu dari dokumen deskripsi.