Memublikasikan API Anda

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:

1. Pilih produk API yang ingin dipublikasikan ke portal Anda.
2. Dokumentasi referensi API Render dari snapshot dokumen OpenAPI atau skema GraphQL Anda agar developer aplikasi dapat mempelajari API Anda. (Untuk mengetahui informasi selengkapnya tentang snapshot, lihat Apa itu snapshot?)

Apa yang dipublikasikan ke portal?

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 Anda 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 aman 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 banyak lagi, 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, yaitu implementasi referensi GraphQL IDE yang dikembangkan oleh GraphQL Foundation.

Developer dapat menggunakan GraphQL Explorer untuk menjelajahi 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 di sepanjang siklus proses API. Dokumen yang sama digunakan di setiap fase dalam siklus proses API, mulai dari pengembangan hingga publikasi hingga pemantauan. Saat memodifikasi dokumen, Anda harus mengetahui dampak perubahan terhadap API selama fase siklus proses lainnya, seperti yang dijelaskan dalam artikel 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 dari dokumen tersebut. Jika Anda mengubah dokumen, Anda dapat memutuskan untuk mengambil ringkasan 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 mendaftarkan aplikasi mereka. URL callback biasanya menetapkan URL aplikasi yang ditetapkan untuk menerima kode otorisasi atas nama aplikasi klien. Untuk mengetahui informasi selengkapnya, lihat Menerapkan jenis pemberian kode otorisasi.

Anda dapat mengonfigurasi apakah akan mewajibkan URL callback selama pendaftaran aplikasi atau tidak saat menambahkan API ke portal Anda. Anda dapat mengubah setelan ini kapan saja, seperti yang dijelaskan dalam 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 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:

• Menambahkan dukungan CORS ke proxy API Anda untuk menerapkan permintaan lintas origin sisi klien

  CORS adalah mekanisme standar yang memungkinkan panggilan JavaScript XMLHttpRequest (XHR) yang dijalankan di halaman web untuk berinteraksi dengan resource dari domain non-asal. CORS adalah solusi yang umum diterapkan untuk "kebijakan origin yang sama" yang diterapkan oleh semua browser.

• Perbarui 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.

Mempelajari katalog API

Untuk melihat katalog API: Akun Layanan 1. Pilih Publikasikan > Portal dan pilih portal Anda. 2. Klik API Catalog di halaman beranda portal. Atau, Anda dapat memilih API Catalog 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 telah dijelaskan dalam gambar sebelumnya, tab API memungkinkan Anda:

• Lihat detail API yang tersedia di portal Anda
• Menambahkan API ke portal Anda
• Edit API di portal Anda dengan melakukan satu atau beberapa tugas berikut:
  • Mengelola ringkasan 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
• Identifikasi spesifikasi yang tidak berlaku atau yang telah dihapus dari penyimpanan spesifikasi dengan cepat
• Mengidentifikasi "usang" dengan cepat API yang produk API terkaitnya telah dihapus dari Edge, dan membuat ulang produk API atau menghapus API dari portal Anda

Menambahkan API ke portal

Untuk menambahkan API ke portal Anda:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.

3. Klik +.

   Tambahkan produk API ke dialog katalog akan ditampilkan.

4. Pilih produk API yang ingin ditambahkan ke portal Anda.

5. Klik Berikutnya. Halaman detail API akan ditampilkan.

6. Konfigurasi 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 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 di lain waktu, seperti yang dijelaskan dalam Mengedit judul dan deskripsi tampilan.
   Deskripsi tampilan	Perbarui deskripsi API Anda yang ditampilkan dalam katalog. Secara default, deskripsi produk API akan digunakan. Anda dapat mengubah deskripsi tampilan nanti, seperti yang dijelaskan dalam 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 di lain waktu, 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 penyimpanan spesifikasi. Klik tab Upload File dan upload file. Klik tab Import from a URL dan impor spesifikasi dari URL. Klik Pilih. Untuk menggunakan skema GraphQL: Pilih GraphQL Schema. Klik Pilih Dokumen. 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 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 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 untuk melihat API. Audiens yang dipilih untuk memilih audiens tertentu yang Anda inginkan untuk 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. 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 Pilih. Anda dapat menambahkan gambar nanti, seperti yang dijelaskan dalam Mengelola image untuk kartu API. Saat menentukan gambar dengan URL eksternal, gambar tersebut tidak akan diupload ke aset Anda; Selain itu, pemuatan gambar di portal terintegrasi akan bergantung pada ketersediaannya, yang mungkin diblokir atau dibatasi oleh kebijakan keamanan konten.
   Kategori	Tambahkan kategori tempat API akan diberi tag sehingga 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.

7. Klik Simpan.

Mengelola ringkasan dokumen

Setelah memublikasikan API, Anda dapat mengambil ringkasan baru dari dokumen OpenAPI atau GraphQL kapan saja untuk memperbarui dokumentasi referensi API yang dipublikasikan di portal Anda.

Untuk mengelola ringkasan dokumen:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Periksa status snapshot. Jika sudah tidak berlaku, pesan berikut akan ditampilkan:
5. Klik .
6. Lakukan salah satu dari tugas berikut:
   • Untuk memuat ulang snapshot dokumen OpenAPI yang sudah tidak berlaku, klik Refresh Snapshot.
   • Untuk mengubah dokumen yang digunakan untuk membuat dokumentasi API, di bagian dokumentasi API, klik Select Document dan pilih dokumen baru.
7. Klik Simpan.

Dokumentasi referensi API dirender dari dokumen dan ditambahkan ke halaman Referensi API. Status snapshot diperbarui menjadi saat ini:

Memublikasikan atau membatalkan publikasi API di portal

Untuk memublikasikan atau membatalkan publikasi API di portal Anda:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik .
5. Di bagian detail API, pilih atau batalkan pilihan Dipublikasikan (tercantum dalam katalog) untuk memublikasikan atau membatalkan publikasi API di portal Anda.
6. 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 terdaftar dalam rilis beta fitur pengelolaan audiens)

Untuk mengelola visibilitas API di portal Anda:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik .
5. Di bagian visibilitas API, pilih salah satu opsi berikut:

6. Pilih setelan visibilitas. Jika Anda telah terdaftar dalam rilis beta fitur audiens, pilih salah satu opsi berikut:

   • Publik (terlihat oleh siapa saja) untuk mengizinkan semua pengguna melihat halaman.
   • Pengguna yang diautentikasi untuk hanya mengizinkan pengguna terdaftar melihat halaman.
   • Audiens yang dipilih untuk memilih audiens tertentu yang Anda inginkan untuk melihat halaman. Lihat Mengelola audiens untuk portal Anda.
   Jika tidak, pilih salah satu opsi berikut:
   • Pengguna anonim untuk mengizinkan semua pengguna melihat halaman.
   • Pengguna terdaftar berarti hanya pengguna terdaftar yang diizinkan melihat halaman.

7. Klik Kirim.

Mengelola URL callback untuk API

Mengelola URL callback untuk API. Lihat artikel Tentang URL callback.

Untuk mengelola URL callback untuk API:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik .
5. Di bagian detail API, pilih atau batalkan pilihan Dipublikasikan (tercantum di katalog) untuk memublikasikan atau membatalkan publikasi API di portal Anda.
6. Klik Simpan.

Mengelola image untuk kartu API

Kelola gambar yang muncul bersama kartu API pada halaman API dengan menambahkan atau mengubah gambar saat ini.

Untuk mengelola image kartu API:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik .

5. 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 yang menggunakan URL eksternal 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; Selain itu, pemuatan gambar dalam portal akan bergantung pada ketersediaannya, yang mungkin diblokir atau dibatasi oleh kebijakan keamanan konten.

6. Klik Simpan.

Memberi tag pada API menggunakan kategori

Beri tag pada API menggunakan kategori dengan salah satu cara berikut:

• Kelola kategori yang akan diberi tag API saat mengedit API, seperti yang dijelaskan di bawah ini.
• Mengelola API yang diberi tag ke kategori saat mengedit kategori.

Untuk memberi tag API ke kategori saat mengedit API:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik .
5. Klik dalam 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.
6. Ulangi untuk memberi tag API ke kategori lainnya.
7. Klik Simpan.

Mengedit judul dan deskripsi tampilan

Untuk mengedit judul dan deskripsi tampilan:

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik .
5. Edit kolom Judul tampilan dan Deskripsi tampilan sesuai kebutuhan.
6. Klik Simpan.

Menghapus API dari portal

Untuk menghapus API dari portal Anda:

1. Akses katalog API.
2. Pilih API, jika belum dipilih.
3. Posisikan kursor Anda di atas API dalam daftar untuk menampilkan menu tindakan.
4. 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 portal live. Tambahkan dan kelola kategori, seperti yang dijelaskan di bagian berikut.

Menjelajahi halaman Kategori

Untuk melihat halaman Kategori:

1. Pilih Publikasikan > Portal dan pilih portal Anda.
2. Klik API Catalog di halaman beranda portal.

   Atau, Anda dapat memilih API Catalog di menu drop-down portal pada menu navigasi atas.

3. Klik tab Kategori.

Tab Kategori di 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 tempat kategori tersebut 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 tersedia saat menambahkan atau mengedit API lainnya.

Untuk menambahkan kategori secara manual:

1. Akses halaman Kategori.
2. Klik +.
3. Masukkan nama kategori baru.
4. Secara opsional, pilih satu atau beberapa API untuk diberi tag ke kategori.
5. Klik Buat.

Edit kategori

Untuk mengedit kategori:

1. Akses halaman Kategori.
2. Klik .
3. Edit nama kategori.
4. Tambahkan atau hapus tag API.
5. Klik Simpan.

Menghapus kategori

Saat Anda menghapus kategori, semua tag API ke kategori tersebut juga akan dihapus.

Untuk menghapus kategori:

1. Akses halaman Kategori.
2. Posisikan kursor di atas kategori yang ingin Anda edit untuk menampilkan menu tindakan.
3. Klik .
4. Edit nama kategori.
5. Tambahkan atau hapus API.
6. Klik Simpan.

Memecahkan masalah terkait API yang dipublikasikan

Bagian berikut memberikan informasi untuk membantu Anda memecahkan masalah error tertentu dengan API yang telah 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 penyelesaiannya:

• Untuk error konten campuran, error tersebut mungkin disebabkan oleh masalah swagger-ui yang diketahui. Salah satu kemungkinan 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 memungkinkan permintaan lintas origin sisi klien. Lihat Mengonfigurasi proxy API untuk mendukung Coba API ini.

Kesalahan: 'Access-Control-Allow-Origin' header 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 MenetapkanMessage untuk menggunakan <Set> guna menetapkan header CORS, bukan <Add>, seperti yang ditunjukkan dalam kutipan di bawah. Untuk mengetahui informasi selengkapnya, lihat 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 menerima error Request header field not allowed, seperti contoh di bawah ini, Anda mungkin perlu mengupdate 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 di 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 Bearer yang sesuai dengan RFC yang diharapkan. Respons token_type yang tidak valid ini dapat mengakibatkan error Access denied saat menggunakan Coba API ini.

Untuk memperbaiki masalah ini, Anda dapat membuat kebijakan JavaScript atau MenetapkanMessage untuk mengubah output kebijakan ke dalam format yang mematuhi kebijakan. Untuk informasi selengkapnya, lihat perilaku yang tidak sesuai dengan RFC.