Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Publikasikan API ke portal Anda agar tersedia untuk digunakan oleh developer aplikasi, seperti yang dijelaskan di bagian berikut.
Ringkasan publikasi API
Proses publikasi API ke portal Anda terdiri dari dua langkah:
- Pilih produk API yang ingin dipublikasikan ke portal Anda.
- Dokumentasi referensi API Render dari snapshot dokumen OpenAPI atau skema GraphQL Anda untuk memungkinkan developer aplikasi mempelajari API Anda. (Untuk informasi selengkapnya tentang snapshot, lihat Apa yang dimaksud dengan snapshot?)
Apa yang dipublikasikan ke portal?
Saat Anda memublikasikan API, update berikut akan otomatis dilakukan pada portal:Halaman API (disertakan dengan portal contoh) menyediakan daftar semua API yang dipublikasikan ke portal Anda, yang tercantum dalam urutan abjad, dengan link ke masing-masing dokumentasi referensi API untuk informasi lebih lanjut. Secara opsional, Anda dapat menyesuaikan hal berikut:
- Gambar ditampilkan untuk setiap kartu API
- Kategori yang digunakan untuk memberi tag pada API agar developer dapat menemukan API terkait di halaman API
SmartDocs (OpenAPI)
Saat Anda memublikasikan API menggunakan dokumen OpenAPI, dokumentasi referensi SmartDocs API akan ditambahkan ke portal Anda.
Developer dapat meninjau dokumentasi referensi SmartDocs API dan menggunakan panel Coba API ini untuk membuat permintaan API dan melihat outputnya. Coba API ini berfungsi dengan endpoint yang tidak aman atau endpoint yang diamankan menggunakan Dasar, Kunci API, atau Autentikasi OAuth, berdasarkan metode keamanan yang ditentukan dalam dokumen OpenAPI Anda. Untuk OAuth, alur berikut didukung: kode otorisasi, sandi, dan kredensial klien.
Klik untuk meluaskan panel Coba API ini. Panel yang diperluas memungkinkan Anda melihat panggilan curl dan contoh kode dalam berbagai format, seperti HTTP, Python, Node.js, dan banyak lagi, seperti yang ditampilkan di bawah ini.
Penjelajah GraphQL
Saat Anda memublikasikan API menggunakan skema GraphQL, GraphQL Explorer akan ditambahkan ke portal Anda. GraphQL Explorer adalah simulasi interaktif untuk menjalankan kueri terhadap API Anda. Penjelajahnya didasarkan pada GraphiQL, yakni implementasi referensi GraphQL IDE yang dikembangkan oleh GraphQL Foundation.
Developer dapat menggunakan GraphQL Explorer untuk mempelajari dokumentasi interaktif berbasis skema, membangun dan menjalankan kueri, melihat hasil kueri, serta mendownload skema. Untuk mengamankan akses ke API Anda, developer dapat meneruskan header otorisasi di panel Request Headers.
Untuk mengetahui informasi selengkapnya tentang GraphQL, lihat graphql.org.
Apa itu snapshot?
Setiap dokumen OpenAPI atau GraphQL berfungsi sebagai sumber kebenaran selama siklus proses API. Dokumen yang sama digunakan di setiap fase dalam siklus proses API, mulai dari pengembangan, publikasi, hingga pemantauan. Saat memodifikasi dokumen, Anda harus mengetahui dampak perubahan tersebut pada API melalui fase siklus proses lainnya, seperti yang dijelaskan dalam Apa yang terjadi jika saya mengubah dokumen?
Saat memublikasikan API, Anda akan mengambil snapshot dokumen OpenAPI atau GraphQL untuk merender dokumentasi referensi API. Snapshot tersebut mewakili versi dokumen tertentu. Jika Anda memodifikasi dokumen, Anda dapat memutuskan untuk mengambil snapshot dokumen lainnya untuk mencerminkan perubahan terbaru dalam dokumentasi referensi API.
Tentang URL callback
Jika aplikasi Anda memerlukan URL callback, seperti saat menggunakan jenis pemberian kode otorisasi OAuth 2.0 (sering disebut "three-legged OAuth"), Anda dapat mewajibkan developer untuk menentukan URL callback saat mereka mendaftarkan aplikasi. URL callback biasanya menentukan URL aplikasi yang ditetapkan untuk menerima kode otorisasi atas nama aplikasi klien. Untuk informasi selengkapnya, lihat Mengimplementasikan jenis pemberian kode otorisasi.
Anda dapat mengonfigurasi apakah akan mewajibkan URL callback atau tidak saat pendaftaran aplikasi saat menambahkan API ke portal. Anda dapat mengubah setelan ini kapan saja, seperti yang dijelaskan di Mengelola URL callback untuk API.
Saat mendaftarkan aplikasi, developer harus memasukkan URL callback untuk semua API yang memerlukannya, seperti yang dijelaskan dalam Mendaftarkan aplikasi.
Konfigurasikan proxy API Anda untuk mendukung "Coba API ini"
Sebelum memublikasikan API menggunakan dokumen OpenAPI, Anda harus mengonfigurasi proxy API untuk mendukung pembuatan permintaan pada panel Coba API ini di dokumentasi referensi SmartDocs API, sebagai berikut:
- Menambahkan dukungan CORS ke proxy API untuk menerapkan permintaan lintas origin sisi klien
CORS adalah mekanisme standar yang memungkinkan panggilan XMLHttpRequest (XHR) JavaScript yang dieksekusi di halaman web berinteraksi dengan resource dari domain non-asal. CORS adalah solusi yang umumnya diimplementasikan untuk "kebijakan asal yang sama" yang diterapkan oleh semua browser.
- Memperbarui konfigurasi proxy API jika Anda menggunakan autentikasi dasar atau OAuth2
Tabel berikut meringkas persyaratan konfigurasi proxy API untuk mendukung panel Coba API ini di dokumentasi referensi SmartDocs API berdasarkan akses autentikasi.
Akses Auth | Persyaratan konfigurasi kebijakan |
---|---|
Tidak ada atau kunci API | Tambahkan dukungan CORS ke proxy API Anda. Untuk mempermudah, gunakan contoh solusi CORS yang disediakan di GitHub atau ikuti langkah-langkah yang dijelaskan dalam Menambahkan dukungan CORS ke proxy API. |
Autentikasi dasar | Lakukan langkah-langkah berikut:
|
OAuth2 |
|
Jelajahi katalog API
Untuk melihat katalog API: 1. Pilih Publikasikan > Portal dan pilih portal Anda. 2. Klik Katalog API di halaman beranda portal. Atau, Anda dapat memilih Katalog API di menu drop-down portal pada menu navigasi atas.
Tab API dalam katalog API menampilkan daftar API yang telah ditambahkan ke portal Anda.
Seperti yang ditandai dalam gambar sebelumnya, tab API memungkinkan Anda:
- Lihat detail API yang tersedia di portal Anda
- Menambahkan API ke portal
- Edit API di portal Anda dengan melakukan satu atau beberapa tugas berikut:
- Mengelola snapshot dokumen yang terkait dengan produk API untuk memperbarui dokumentasi referensi API
- Memublikasikan atau membatalkan publikasi API di portal
- Mengelola visibilitas API di portal Anda:
- Mengelola URL callback untuk API
- Mengelola image untuk kartu API
- Memberi tag pada API menggunakan kategori
- Mengedit judul dan deskripsi API
- Menghapus API dari portal Anda
- Mengelola kategori yang digunakan untuk menemukan API terkait
- Dengan cepat mengidentifikasi spesifikasi yang sudah tidak berlaku atau yang telah dihapus dari toko spesifikasi
- Identifikasi dengan cepat API "usang" yang produk API terkaitnya telah dihapus dari Edge, dan buat ulang produk API atau hapus API tersebut dari portal Anda
Menambahkan API ke portal Anda
Untuk menambahkan API ke portal Anda:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
Klik +.
Dialog Tambahkan produk API ke katalog akan ditampilkan.
Pilih produk API yang ingin ditambahkan ke portal Anda.
Klik Berikutnya. Halaman detail API akan ditampilkan.
Konfigurasikan konten dokumentasi referensi API dan visibilitasnya di portal:
Field Deskripsi Dipublikasikan Pilih Dipublikasikan untuk memublikasikan API ke portal Anda. Hapus centang pada kotak jika Anda belum siap memublikasikan API. Anda dapat mengubah setelan ini nanti, seperti yang dijelaskan dalam Memublikasikan atau membatalkan publikasi API di portal. Judul tampilan Perbarui judul API Anda yang ditampilkan di katalog. Secara default, nama produk API akan digunakan. Anda dapat mengubah judul tampilan nanti, seperti yang dijelaskan di Mengedit judul dan deskripsi tampilan. Deskripsi tampilan Perbarui deskripsi API Anda yang ditampilkan di katalog. Secara default, deskripsi produk API akan digunakan. Anda dapat mengubah deskripsi tampilan nanti, seperti yang dijelaskan di Mengedit judul dan deskripsi tampilan. Wajibkan developer untuk menentukan URL callback Aktifkan jika Anda ingin mewajibkan developer aplikasi menentukan URL callback. Anda dapat menambahkan atau memperbarui URL callback nanti, seperti yang dijelaskan dalam Mengelola URL callback untuk API. Dokumentasi API Untuk menggunakan dokumen OpenAPI: - Pilih Dokumen OpenAPI.
- Klik Pilih dokumen.
- Lakukan salah satu langkah berikut:
- Klik tab My Specs dan pilih spesifikasi dari toko spesifikasi.
- Klik tab Upload File lalu upload file.
- Klik tab Impor dari URL dan impor spesifikasi dari URL.
- Klik Select.
Untuk menggunakan skema GraphQL:
- Pilih GraphQL Schema.
- Klik Select Document.
- Buka dan pilih skema GraphQL.
- Klik Select.
Atau, Anda dapat memilih Tidak ada dokumentasi dan menambahkannya nanti setelah API ditambahkan, seperti yang dijelaskan dalam Mengelola ringkasan dokumen.
Visibilitas API Jika Anda belum terdaftar dalam rilis beta fitur pengelolaan audiens, pilih salah satu opsi berikut:
- Pengguna anonim untuk mengizinkan semua pengguna melihat API.
- Pengguna terdaftar untuk hanya mengizinkan pengguna terdaftar yang dapat melihat API.
Jika Anda telah terdaftar dalam rilis beta fitur pengelolaan audiens, pilih salah satu opsi berikut:
- Publik (terlihat oleh siapa saja) untuk mengizinkan semua pengguna melihat API.
- Pengguna yang diautentikasi untuk hanya mengizinkan pengguna terdaftar yang dapat melihat API.
- Audiens yang dipilih untuk memilih audiens tertentu yang Anda inginkan agar dapat melihat API.
Anda dapat mengelola visibilitas audiens nanti, seperti yang dijelaskan dalam Mengelola visibilitas API di portal Anda.
Gambar tampilan Untuk menampilkan gambar di kartu API di halaman API, klik Select image. Pada dialog Pilih gambar, pilih gambar yang ada, upload gambar baru, atau berikan URL gambar eksternal, lalu klik Pilih. Lihat pratinjau thumbnail API, lalu klik Select. Anda dapat menambahkan gambar nanti, seperti yang dijelaskan di Mengelola gambar untuk kartu API. Saat menentukan gambar dengan URL eksternal, gambar tidak akan diupload ke aset Anda. Selain itu, pemuatan gambar di portal yang terintegrasi akan bergantung pada ketersediaannya, yang mungkin akan diblokir atau dibatasi oleh kebijakan keamanan konten. Kategori Tambahkan kategori tempat API akan diberi tag agar developer aplikasi dapat menemukan API terkait di halaman API. Untuk mengidentifikasi kategori:
- Pilih kategori dari menu drop-down.
- Tambahkan kategori baru dengan mengetik namanya, lalu menekan Enter. Kategori baru akan ditambahkan ke halaman Kategori dan disediakan saat menambahkan atau mengedit API lainnya.
Klik Save.
Mengelola snapshot dokumen
Setelah memublikasikan API, Anda dapat mengambil snapshot baru dari dokumen OpenAPI atau GraphQL untuk memperbarui dokumentasi referensi API yang dipublikasikan di portal Anda kapan saja.
Untuk mengelola snapshot dokumen:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
- Klik baris API yang ingin Anda edit.
- Periksa status snapshot.
Jika alamat email tidak berlaku lagi, pesan berikut akan ditampilkan:
- Klik
.
- Lakukan salah satu tugas berikut:
- Untuk memuat ulang snapshot dokumen OpenAPI yang sudah tidak berlaku, klik Refresh Snapshot.
- Untuk mengubah dokumen yang digunakan untuk membuat dokumentasi untuk API, di bagian dokumentasi API, klik Select Document, lalu pilih dokumen baru.
- Klik Save.
Dokumentasi referensi API dirender dari dokumen dan ditambahkan ke halaman Referensi API. Status snapshot diperbarui menjadi versi saat ini:
Memublikasikan atau membatalkan publikasi API di portal
Untuk memublikasikan atau membatalkan publikasi API di portal Anda:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
- Klik baris API yang ingin Anda edit.
- Klik
.
- Di bagian detail API, pilih atau batalkan pilihan Dipublikasikan (tercantum dalam katalog) untuk masing-masing memublikasikan atau membatalkan publikasi API di portal Anda.
- Klik Save.
Mengelola visibilitas API di portal Anda
Kelola visibilitas API di portal Anda dengan mengizinkan akses ke:
- Publik (dapat dilihat oleh siapa saja)
- Pengguna yang diautentikasi
- Audiens yang dipilih (jika Anda telah terdaftar dalam rilis beta fitur pengelolaan audiens)
Untuk mengelola visibilitas API di portal Anda:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
- Klik baris API yang ingin Anda edit.
- Klik
.
- Pada visibilitas API, pilih salah satu opsi berikut:
Pilih setelan visibilitas. Jika Anda telah terdaftar dalam rilis beta fitur audiens, pilih salah satu opsi berikut:
- Publik (terlihat oleh siapa saja) untuk memungkinkan semua pengguna melihat halaman.
- Pengguna yang diautentikasi untuk hanya mengizinkan pengguna terdaftar yang melihat halaman.
- Audiens yang dipilih untuk memilih audiens tertentu yang Anda inginkan agar dapat melihat halaman Anda. Lihat Mengelola audiens untuk portal Anda.
- Pengguna anonim untuk mengizinkan semua pengguna melihat halaman.
- Pengguna terdaftar untuk hanya mengizinkan pengguna terdaftar yang melihat halaman.
Klik Kirim.
Mengelola URL callback untuk API
Mengelola URL callback untuk API. Lihat Tentang URL callback.
Untuk mengelola URL callback untuk API:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
- Klik baris API yang ingin Anda edit.
- Klik
.
- Di bagian detail API, pilih atau batalkan pilihan Dipublikasikan (tercantum dalam katalog) untuk masing-masing memublikasikan atau membatalkan publikasi API di portal Anda.
- Klik Save.
Mengelola gambar untuk kartu API
Kelola image yang muncul bersama kartu API di halaman API dengan menambahkan atau mengubah image saat ini.
Untuk mengelola image kartu API:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
- Klik baris API yang ingin Anda edit.
- Klik
.
Di bagian detail API:
- Klik Pilih gambar untuk menentukan atau mengupload gambar jika tidak ada gambar yang dipilih saat ini.
- Klik Ubah gambar untuk menentukan atau mengupload gambar lain.
- Klik x pada gambar untuk menghapusnya.
Saat menentukan gambar, tentukan gambar dengan URL eksternal yang digunakan untuk item katalog, atau jalur file untuk file gambar yang disimpan di portal, misalnya,
/files/book-tree.jpg
. Saat menentukan URL gambar eksternal, gambar tidak akan diupload ke aset Anda; selain itu, pemuatan gambar di portal terintegrasi akan bergantung pada ketersediaannya, yang mungkin akan diblokir atau dibatasi oleh kebijakan keamanan konten.Klik Save.
Memberi tag pada API menggunakan kategori
Beri tag API menggunakan kategori dengan salah satu cara berikut:
- Kelola kategori yang akan diberi tag pada API saat mengedit API, seperti yang dijelaskan di bawah.
- Mengelola API yang diberi tag ke kategori saat mengedit kategori.
Untuk memberi tag pada API ke kategori saat mengedit API:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
- Klik baris API yang ingin Anda edit.
- Klik
.
- Klik kolom Kategori dan lakukan salah satu langkah berikut:
- Pilih kategori dari menu drop-down.
- Tambahkan kategori baru dengan mengetik namanya, lalu menekan Enter. Kategori baru akan ditambahkan ke halaman Kategori dan disediakan saat menambahkan atau mengedit API lainnya.
- Ulangi untuk memberi tag pada API ke kategori lainnya.
- Klik Save.
Edit judul dan deskripsi tampilan
Untuk mengedit judul dan deskripsi tampilan:
- Mengakses katalog API.
- Klik tab APIs, jika belum dipilih.
- Klik baris API yang ingin Anda edit.
- Klik
.
- Edit kolom Judul tampilan dan Deskripsi tampilan, sesuai kebutuhan.
- Klik Save.
Menghapus API dari portal Anda
Untuk menghapus API dari portal Anda:
- Mengakses katalog API.
- Pilih API, jika belum dipilih.
- Arahkan kursor ke API dalam daftar untuk menampilkan menu tindakan.
- Klik
.
Mengelola kategori yang digunakan untuk menemukan API terkait
Beri tag pada API menggunakan kategori agar developer aplikasi dapat menemukan API terkait di halaman API dari portal live. Menambahkan dan mengelola kategori, seperti yang dijelaskan di bagian berikut.
Menjelajahi halaman Kategori
Untuk melihat halaman Kategori:
- Pilih Publikasikan > Portal dan pilih portal Anda.
- Klik Katalog API di halaman beranda portal.
Atau, Anda dapat memilih Katalog API di menu drop-down portal pada menu navigasi atas.
- Klik tab Kategori.
Tab Kategori dalam katalog API menampilkan daftar kategori yang telah ditentukan untuk portal Anda.
Seperti yang disorot dalam gambar sebelumnya, halaman API memungkinkan Anda:
- Melihat kategori dan API yang diberi tag
- Menambahkan kategori
- Mengedit kategori
- Menghapus kategori
- Kelola API yang dipublikasikan ke portal Anda. Lihat Menjelajahi katalog API
Menambahkan kategori
Tambahkan kategori dengan salah satu cara berikut:
- Masukkan nama kategori saat menambahkan API ke portal
- Tambahkan kategori secara manual seperti yang dijelaskan di bawah
Kategori baru akan ditambahkan ke halaman Kategori dan disediakan saat menambahkan atau mengedit API lainnya.
Untuk menambahkan kategori secara manual:
- Akses halaman Kategori.
- Klik +.
- Masukkan nama kategori baru.
- Secara opsional, pilih satu atau beberapa API untuk diberi tag pada kategori.
- Klik Create.
Mengedit kategori
Untuk mengedit kategori:
- Akses halaman Kategori.
- Klik
.
- Edit nama kategori.
- Menambahkan atau menghapus tag API.
- Klik Save.
Menghapus kategori
Saat Anda menghapus sebuah kategori, semua tag API pada kategori tersebut juga akan dihapus.
Untuk menghapus kategori:
- Akses halaman Kategori.
- Arahkan kursor ke kategori yang ingin Anda edit untuk menampilkan menu tindakan.
- Klik
.
- Edit nama kategori.
- Menambahkan atau menghapus API.
- Klik Save.
Memecahkan masalah terkait API yang dipublikasikan
Bagian berikut memberikan informasi untuk membantu Anda memecahkan masalah error tertentu pada API yang kami publikasikan.
Error: Gagal mengambil error yang ditampilkan saat menggunakan Coba API ini
Saat menggunakan Coba API ini, jika error TypeError: Failed to fetch
ditampilkan, pertimbangkan kemungkinan penyebab dan penyelesaian berikut:
Untuk error konten campuran, error tersebut mungkin disebabkan oleh masalah swagger-ui umum. Salah satu solusi yang mungkin adalah memastikan bahwa Anda menentukan HTTPS sebelum HTTP dalam definisi
schemes
di dokumen OpenAPI Anda. Contoh:schemes: - https - http
Untuk error pembatasan Cross-Origin Resource Sharing (CORS), pastikan CORS didukung untuk proxy API Anda. CORS adalah mekanisme standar yang mengaktifkan permintaan lintas origin sisi klien. Lihat Mengonfigurasi proxy API untuk mendukung Coba API ini.
Error: Header 'Access-Control-Allow-Origin' berisi beberapa nilai '*, *', tetapi hanya satu nilai yang diizinkan
Saat menggunakan Coba API ini, Anda mungkin menerima pesan error berikut jika header Access-Control-Allow-Origin
sudah ada:
The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.
Untuk memperbaiki error ini, ubah kebijakan ProvideMessage untuk menggunakan <Set>
guna menetapkan header CORS, bukan <Add>
, seperti yang ditunjukkan dalam kutipan di bawah.
Untuk informasi selengkapnya, baca artikel komunitas yang relevan.
<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors"> <DisplayName>Add CORS</DisplayName> <FaultRules/> <Properties/> <Set> <Headers> <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header> <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header> <Header name="Access-Control-Max-Age">3628800</Header> <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header> </Headers> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
Error: Bidang header permintaan tidak diizinkan
Saat menggunakan Coba API ini, jika Anda menerima error Request header field not allowed
, mirip dengan contoh di bawah, Anda mungkin perlu memperbarui header yang didukung dalam kebijakan CORS. Contoh:
Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response
Dalam contoh ini, Anda perlu menambahkan header content-type
ke bagian Access-Control-Allow-Headers
dalam kebijakan Penugasan CORS, seperti yang dijelaskan dalam bagian Melampirkan kebijakan Tambahkan kebijakan CORS ke proxy API baru.
Error: Akses ditolak saat memanggil proxy API menggunakan OAuth2
Kebijakan OAuthV2 Apigee menampilkan respons token yang berisi properti tertentu yang tidak sesuai dengan RFC. Misalnya, kebijakan akan menampilkan token dengan nilai BearerToken
, bukan nilai yang sesuai dengan RFC yang diharapkan Bearer
. Respons token_type
yang tidak valid ini dapat menyebabkan error Access denied
saat menggunakan Coba API ini.
Untuk memperbaiki masalah ini, Anda dapat membuat kebijakan JavaScript atau DefineMessage untuk mengubah output kebijakan ke format yang mematuhi kebijakan. Untuk informasi selengkapnya, lihat perilaku yang tidak sesuai dengan RFC.