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 merupakan proses dua langkah:
- Pilih produk API yang ingin dipublikasikan ke portal Anda.
- Render dokumentasi referensi API dari snapshot dokumen OpenAPI atau skema GraphQL untuk memungkinkan developer aplikasi mempelajari API Anda. (Untuk informasi selengkapnya tentang snapshot, lihat Apa itu snapshot?)
Apa yang dipublikasikan ke portal?
Saat Anda memublikasikan API, update berikut akan otomatis dilakukan ke portal Anda:Halaman API (disertakan dengan portal contoh) menyediakan daftar semua API yang dipublikasikan ke portal Anda, yang tercantum sesuai urutan abjad, disertai link ke masing-masing dokumentasi referensi API untuk informasi selengkapnya. 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 hasilnya. Coba API ini berfungsi dengan endpoint yang tidak aman atau endpoint yang diamankan menggunakan Autentikasi 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 lainnya, seperti yang ditunjukkan di bawah ini.
Penjelajah GraphQL
Saat Anda memublikasikan API menggunakan skema GraphQL, GraphQL Explorer akan ditambahkan ke portal Anda. GraphQL Explorer adalah playground interaktif untuk menjalankan kueri terhadap API Anda. Penjelajah ini didasarkan pada GraphiQL, 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, dan mendownload skema. Untuk mengamankan akses ke API, 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 di sepanjang siklus proses API. Dokumen yang sama digunakan di setiap fase dalam siklus proses API, mulai dari pengembangan, publikasi, hingga pemantauan. Saat mengubah dokumen, Anda harus memahami dampak perubahan tersebut terhadap 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 tertentu dokumen. 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 Menerapkan jenis pemberian kode otorisasi.
Anda dapat mengonfigurasi apakah mewajibkan URL callback selama pendaftaran aplikasi atau tidak 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.
Konfigurasi proxy API Anda untuk mendukung "Coba API ini"
Sebelum mempublikasikan API menggunakan dokumen OpenAPI, Anda harus mengonfigurasi proxy API untuk mendukung pembuatan permintaan pada panel Coba API ini dalam dokumentasi referensi SmartDocs API, sebagai berikut:
- Tambahkan dukungan CORS ke proxy API Anda 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-origin. CORS adalah solusi yang umumnya diimplementasikan untuk "kebijakan origin yang sama" yang diterapkan oleh semua browser.
- Mengupdate konfigurasi proxy API jika Anda menggunakan autentikasi dasar atau OAuth2
Tabel berikut merangkum persyaratan konfigurasi proxy API untuk mendukung panel Coba API ini dalam 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 memudahkan, 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 |
|
Pelajari katalog API
Untuk melihat katalog API:
1. Pilih Publikasikan > Portal, lalu 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 di katalog API menampilkan daftar API yang telah ditambahkan ke portal Anda.
Seperti yang disorot dalam gambar sebelumnya, tab API memungkinkan Anda untuk:
- 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
- Mengelola kategori yang digunakan untuk menemukan API terkait
- Identifikasi spesifikasi yang tidak berlaku lagi atau yang telah dihapus dari toko spesifikasi dengan cepat
- Identifikasi dengan cepat API "usang" yang produk API terkaitnya telah dihapus dari Edge, dan buat ulang produk API atau hapus API dari portal Anda
Menambahkan API ke portal
Untuk menambahkan API ke portal:
- 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 Next.
Halaman detail API akan ditampilkan.Konfigurasikan konten dokumentasi referensi API dan visibilitasnya di portal:
Kolom Deskripsi Dipublikasikan Pilih Dipublikasikan untuk memublikasikan API ke portal Anda. Hapus centang pada kotak jika Anda belum siap memublikasikan API. Anda dapat mengubah setelan 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 Spesifikasi Saya, lalu pilih spesifikasi dari toko spesifikasi.
- Klik tab Upload File dan upload file.
- Klik tab Impor dari URL dan impor spesifikasi dari URL.
- Klik Pilih.
Untuk menggunakan skema GraphQL:
- Pilih GraphQL Schema.
- Klik Select Document.
- Buka dan pilih skema GraphQL.
- Klik Pilih.
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 melihat API.
Jika Anda telah mendaftar dalam rilis beta fitur pengelolaan audiens, pilih salah satu opsi berikut:
- Publik (terlihat oleh siapa saja) untuk mengizinkan semua pengguna melihat API.
- Pengguna terautentikasi agar hanya pengguna terdaftar yang bisa 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 pada kartu API di halaman API, klik Select image. Di 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. Kategori Tambahkan kategori yang akan diberi tag API untuk memungkinkan developer aplikasi 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 tersedia saat menambahkan atau mengedit API lainnya.
Klik Simpan.
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 sudah tidak berlaku, 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 dan pilih dokumen baru.
- Klik Simpan.
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 memublikasikan atau membatalkan publikasi API di portal Anda.
- Klik Simpan.
Mengelola visibilitas API di portal Anda
Kelola visibilitas API di portal Anda dengan mengizinkan akses ke:
- Publik (terlihat oleh siapa saja)
- Pengguna terautentikasi
- Audiens yang dipilih (jika Anda telah mendaftar 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 terautentikasi agar hanya pengguna terdaftar yang bisa melihat halaman.
- Audiens yang dipilih untuk memilih audiens tertentu yang Anda inginkan agar dapat melihat halaman. Lihat Mengelola audiens untuk portal.
- Pengguna anonim untuk mengizinkan semua pengguna melihat halaman.
- Pengguna terdaftar untuk hanya mengizinkan pengguna terdaftar melihat halaman.
Klik Submit.
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 memublikasikan atau membatalkan publikasi API di portal Anda.
- Klik Simpan.
Mengelola gambar kartu API
Kelola gambar yang muncul bersama kartu API di halaman API dengan menambahkan atau mengubah gambar 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 memilih atau mengupload gambar jika tidak ada gambar yang dipilih saat ini.
- Klik Ubah gambar untuk memilih atau mengupload gambar lain.
- Klik x pada gambar untuk menghapusnya.
Klik Simpan.
Memberi tag pada API menggunakan kategori
Beri tag pada API menggunakan kategori melalui salah satu cara berikut:
- Kelola kategori yang akan diberikan tag 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 tersedia saat menambahkan atau mengedit API lainnya.
- Ulangi untuk memberi tag pada API ke kategori lainnya.
- Klik Simpan.
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 Simpan.
Menghapus API dari portal Anda
Untuk menghapus API dari portal Anda:
- Mengakses katalog API.
- Pilih APIs, jika belum dipilih.
- Posisikan kursor di atas API dalam daftar untuk menampilkan menu tindakan.
- Klik .
Kelola kategori yang digunakan untuk menemukan API terkait
Beri tag pada API menggunakan kategori untuk memungkinkan developer aplikasi menemukan API terkait di halaman API di portal langsung. Tambahkan dan kelola kategori, seperti yang dijelaskan di bagian berikut.
Menjelajahi halaman Kategori
Untuk melihat halaman Kategori:
- Pilih Publikasikan > Portal, lalu 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 untuk:
- 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 menggunakan 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 tersedia saat menambahkan atau mengedit API lainnya.
Untuk menambahkan kategori secara manual:
- Akses halaman Kategori.
- Klik +.
- Masukkan nama kategori baru.
- Opsional, pilih satu atau beberapa API untuk diberi tag ke kategori.
- Klik Create.
Mengedit kategori
Untuk mengedit kategori:
- Akses halaman Kategori.
- Klik .
- Edit nama kategori.
- Menambahkan atau menghapus tag API.
- Klik Simpan.
Menghapus kategori
Saat Anda menghapus sebuah kategori, semua tag API pada kategori tersebut juga akan dihapus.
Untuk menghapus kategori:
- Akses halaman Kategori.
- Posisikan kursor di atas kategori yang ingin Anda edit untuk menampilkan menu tindakan.
- Klik .
- Edit nama kategori.
- Menambahkan atau menghapus API.
- Klik Simpan.
Memecahkan masalah pada API yang dipublikasikan
Bagian berikut memberikan informasi untuk membantu Anda memecahkan masalah error tertentu terkait 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 solusi berikut:
Untuk error konten campuran, error tersebut mungkin disebabkan oleh masalah swagger-ui umum. Salah satu solusinya adalah memastikan bahwa Anda menentukan HTTPS sebelum HTTP dalam definisi
schemes
dalam 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 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: Kolom 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
Pada contoh ini, Anda perlu menambahkan header content-type
ke bagian Access-Control-Allow-Headers
dalam kebijakan TetapkanMessage CORS, seperti yang dijelaskan dalam Melampirkan kebijakan Tambahkan 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 BiddingMessage untuk mengubah output kebijakan ke dalam format yang mematuhi kebijakan. Untuk mengetahui informasi selengkapnya, lihat perilaku yang tidak sesuai dengan RFC.