Memublikasikan API Anda

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Publikasikan API ke portal Anda agar tersedia untuk digunakan oleh aplikasi developer, 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 dokumen OpenAPI Anda atau skema GraphQL agar developer aplikasi dapat mempelajari API Anda. (Untuk informasi selengkapnya, lihat Tentang dokumentasi API)

Apa yang dipublikasikan ke portal?

Saat Anda memublikasikan API, update berikut akan dibuat pada portal Anda secara otomatis:

• Dokumentasi referensi API. Antarmuka yang disediakan tergantung pada baik Anda memublikasikan API menggunakan dokumen OpenAPI maupun skema GraphQL. Lihat:
  • SmartDocs (OpenAPI)
  • Penjelajah GraphQL
• Link ke halaman referensi API ditambahkan ke halaman API

  Halaman API (disertakan dalam portal contoh) menyediakan daftar semua API yang dipublikasikan ke portal Anda, tercantum dalam urutan abjad, dengan link ke referensi API masing-masing dokumentasi untuk informasi selengkapnya. Anda juga dapat menyesuaikan berikut ini:

  • Gambar yang ditampilkan untuk setiap kartu API
  • Kategori yang digunakan untuk memberi tag pada API agar developer dapat menemukan API terkait di halaman API
  Catatan: Anda tidak dapat mengedit konten halaman ini directly; akses tersebut tidak akan muncul dalam daftar halaman di portal Anda. Anda dapat edit gaya laman saat menyesuaikan tema.
  

SmartDocs (OpenAPI)

Saat Anda memublikasikan API menggunakan dokumen OpenAPI, referensi SmartDocs API dokumentasi ditambahkan ke portal Anda.

Catatan: Konsol Google Cloud mendukung Spesifikasi OpenAPI 3.0 dan 2.0 saat Anda membuat dokumentasi referensi API interaktif menggunakan SmartDocs di portal Anda (dijelaskan di bawah), meskipun subkumpulan fitur belum didukung. Referensi jarak jauh dalam dokumen OpenAPI tidak didukung oleh SmartDocs.

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 Dasar, Kunci API, atau Autentikasi OAuth, berdasarkan metode keamanan yang ditentukan dalam dokumen OpenAPI Anda. Untuk OAuth, alur berikut ini didukung: kode otorisasi, {i>password<i}, dan kredensial klien.

Catatan: Pastikan proxy API Anda dikonfigurasi untuk mendukung pembuatan permintaan dari panel Try this API, seperti yang dijelaskan dalam Konfigurasikan proxy API Anda untuk mendukung Coba panel API ini.

Klik Layar penuh untuk meluaskan panel Coba API ini. Panel yang diperluas memungkinkan Anda melihat Panggilan dan contoh kode curl dalam berbagai format, seperti HTTP, Python, Node.js, dan lainnya, seperti yang ditunjukkan di bawah ini.

Catatan: Contoh kode ini tidak dimaksudkan untuk digunakan di lingkungan produksi.

Penjelajah GraphQL

Saat Anda memublikasikan API menggunakan skema GraphQL, GraphQL Explorer ditambahkan ke portal Anda. GraphQL Explorer adalah taman bermain interaktif untuk menjalankan kueri terhadap API Anda. Penjelajah didasarkan pada GraphiQL, implementasi referensi GraphQL IDE yang dikembangkan oleh GraphQL Fondasi.

Developer dapat menggunakan GraphQL Explorer untuk menjelajahi antarmuka berbasis skema dokumentasi interaktif, membuat dan menjalankan kueri, melihat hasil kueri, dan unduh skemanya. Untuk mengamankan akses ke API Anda, developer dapat meneruskan header otorisasi di panel Request Headers. Untuk informasi selengkapnya tentang GraphQL, lihat graphql.org.

Tentang dokumentasi API

Setiap dokumen OpenAPI atau GraphQL berfungsi sebagai sumber kebenaran di seluruh siklus proses API. Dokumen yang sama digunakan di setiap fase dalam API siklus proses, mulai dari pengembangan, publikasi, hingga pemantauan. Saat Anda memodifikasi Anda harus memahami dampak perubahan tersebut terhadap API melalui fase siklus hidup lainnya, seperti dijelaskan dalam Apa yang terjadi jika saya mengubah dokumen?

Saat memublikasikan API ke portal, Anda menyimpan versi OpenAPI atau Dokumen GraphQL untuk merender dokumentasi referensi API. Jika Anda mengubah dokumen tambahan, Anda dapat memutuskan untuk memperbarui dokumentasi referensi API yang dipublikasikan ke portal untuk mencerminkan perubahan terbaru.

Tentang URL callback

Jika aplikasi Anda memerlukan URL callback, seperti saat menggunakan OAuth 2.0 jenis pemberian kode otorisasi (sering disebut sebagai three-legged OAuth), Anda dapat mengharuskan developer untuk menentukan URL callback saat mendaftarkan aplikasi. URL callback biasanya menetapkan URL aplikasi yang ditetapkan untuk menerima kode otorisasi atas nama aplikasi klien. Untuk selengkapnya informasi, lihat Mengimplementasikan jenis pemberian kode otorisasi.

Catatan: URL callback disimpan sebagai atribut khusus di Konsol Google Cloud yang sesuai entitas aplikasi. Jika Anda menggunakan penyedia identitas pihak ketiga, Anda bertanggung jawab untuk menyinkronkan metadata URL callback.

Anda dapat mengonfigurasi apakah akan mewajibkan URL callback selama aplikasi atau tidak saat menambahkan API ke portal Anda. Anda dapat mengubah setelan ini kapan saja, sebagaimana dijelaskan dalam Mengelola URL callback untuk API.

Saat mendaftarkan apl, pengembang harus memasukkan URL callback untuk semua API yang memerlukannya, seperti dijelaskan dalam Mendaftarkan aplikasi.

Konfigurasi proxy API untuk mendukung panel Coba API ini

Catatan: Bagian ini hanya berlaku untuk dokumentasi referensi SmartDocs API, dibuat menggunakan dokumen OpenAPI.

Sebelum memublikasikan API menggunakan dokumen OpenAPI, Anda harus mengonfigurasi proxy API Anda untuk mendukung pembuatan permintaan pada panel Coba API ini di Dokumentasi referensi SmartDocs API, sebagai berikut:

• Menambahkan dukungan CORS ke proxy API Anda untuk menerapkan lintas origin sisi klien permintaan.
  CORS adalah mekanisme standar yang memungkinkan panggilan JavaScript XMLHttpRequest (XHR) yang dijalankan di laman web untuk berinteraksi dengan sumber daya dari domain non-asal. CORS adalah solusi yang umum diimplementasikan untuk kebijakan origin yang sama yang diterapkan oleh semua browser.
• Perbarui konfigurasi proxy API jika Anda menggunakan autentikasi dasar atau OAuth 2.0.

Tabel berikut merangkum persyaratan konfigurasi proxy API untuk mendukung panel Coba API ini dalam dokumentasi referensi SmartDocs API berdasarkan akses otentikasi.

Akses Auth	Persyaratan konfigurasi kebijakan
Tidak ada atau kunci API	Menambahkan dukungan CORS ke proxy API Anda, ikuti langkah-langkah yang dijelaskan di Menambahkan dukungan CORS ke proxy API.
Autentikasi dasar	Lakukan langkah-langkah berikut: Menambahkan dukungan CORS ke proxy API Anda, ikuti langkah-langkah yang dijelaskan di Menambahkan dukungan CORS ke proxy API. Di kebijakan Tambahkan CORS, pastikan Header Access-Control-Allow-Headers mencakup Atribut authorization. Contoh: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>
OAuth 2.0	Menambahkan dukungan CORS ke proxy API Anda, ikuti langkah-langkah yang dijelaskan di Menambahkan dukungan CORS ke proxy API. Di kebijakan Tambahkan CORS, pastikan Header Access-Control-Allow-Headers mencakup Atribut authorization. Contoh: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header> Benar secara faktual perilaku yang tidak sesuai dengan RFC dalam kebijakan OAuth 2.0 Anda. Untuk memudahkan, gunakan contoh solusi OAuth 2.0 yang disediakan di GitHub atau melakukan hal berikut langkah: Pastikan elemen <GrantType> di OAuth 2.0 kebijakan disetel ke request.formparam.grant_type (parameter formulir). Untuk informasi selengkapnya, lihat <GrantType>. Pastikan token_type di kebijakan OAuth 2.0 disetel ke Bearer, dan bukan default BearerToken.

Mengelola API

Kelola API Anda seperti yang dijelaskan di bagian berikut.

Jelajahi API

Gunakan konsol atau perintah curl untuk melihat API yang ada di portal Anda.

Konsol

Untuk melihat katalog API:

1. Pilih Publikasikan > Portal dan pilih portal Anda.

2. Klik API Catalog di halaman beranda portal.
   Atau, Anda dapat memilih Katalog API di menu drop-down portal di menu navigasi atas.
   Tab API dalam katalog API menampilkan daftar API yang memiliki telah ditambahkan ke portal Anda.

   

   

   Seperti yang disorot 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 dokumentasi API
     • Memublikasikan atau membatalkan publikasi API
     • Mengelola visibilitas API
     • 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
   • Mengidentifikasi dengan cepat API usang yang produk API terkaitnya telah dihapus dari Konsol Google Cloud, dan membuat ulang produk API atau menghapus API dari portal Anda

curl

Untuk mencantumkan API menggunakan organizations.sites.apidocs/list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.

Lihat Catatan penomoran halaman untuk petunjuk penggunaan penomoran halaman di payload respons.

Payload respons:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Dengan keterangan:

• modified: Waktu item katalog terakhir diubah dalam milidetik sejak epoch. Contoh, 1698165480000.
• id: ID item katalog. Contoh, 399668.

Catatan penomoran halaman:

• Ukuran halaman: Gunakan pageSize untuk menentukan jumlah item daftar yang akan ditampilkan dalam satu halaman. Defaultnya adalah 25, dan maksimumnya adalah 100. Jika ada halaman tambahan, nextPageToken diisi dengan token:

  curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"
  

  Ganti:

  • PAGE_SIZE dengan jumlah item daftar yang akan ditampilkan dalam satu halaman. Contoh, 10.

  Payload respons:

  {
    "status": "success",
    "message": "one page of apidocs returned",
    "requestId": "918815495",
    "data": [
      {
        "siteId": "my-org-myportal",
        "title": "Hello New World",
        "description": "Simple hello new world example",
        "specId": "apigee",
        "modified": "1699146887000",
        "anonAllowed": true,
        "imageUrl": "/files/camper1.jpg?v=1695841491415",
        "id": "381054",
        "categoryIds": [
          "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
          "61c1014c-89c9-40e6-be3c-69cca3505620"
        ],
        "published": true,
        "apiProductName": "Hello New World"
      }
    ],
    "nextPageToken": "7zcqrin9l6xhi4nbrb9"
  }
  

• Token halaman:

  Gunakan pageToken untuk mengambil halaman berikutnya jika ada lebih dari satu halaman:

  curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
  

  Ganti:

  • PAGE_SIZE dengan jumlah item daftar yang akan ditampilkan dalam satu halaman. Contoh, 10.
  • PAGE_TOKEN dengan nilai nextPageToken. Misalnya, 7zcqrin9l6xhi4nbrb9.

Menambahkan API

Catatan: Lihat Batas portal untuk batasan saat ini.

Untuk menambahkan API ke portal Anda:

Konsol

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

3. Klik Add.

   Dialog Tambahkan produk API ke katalog akan ditampilkan.

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

5. Klik Next. Halaman Detail API akan ditampilkan.

6. Mengonfigurasi 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 di Memublikasikan atau membatalkan publikasi API.
   Judul tampilan	Perbarui judul API Anda yang ditampilkan di katalog. Menurut secara default, nama produk API akan digunakan. Anda dapat mengubah tampilan di lain waktu, sebagaimana dijelaskan dalam Edit 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 dalam Edit 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 di Mengelola URL callback untuk API.
   Dokumentasi API	Untuk menggunakan dokumen OpenAPI: Pilih Dokumen OpenAPI. Klik Pilih Dokumen. Lakukan salah satu langkah berikut: Klik tab Upload File dan upload file. Klik tab Import from a URL dan impor spesifikasi dengan memberikan nama dan URL asal impor. 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 menambahkan dokumentasi di kemudian hari setelah API ditambahkan, seperti dijelaskan dalam Kelola dokumentasi API. Catatan: Saat mengimpor dokumen OpenAPI menggunakan URL, pengalihan tidak akan diikuti.
   Visibilitas	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 yang hanya mengizinkan pengguna terdaftar melihat API. Jika Anda memiliki 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 melihat API. Audiens yang dipilih untuk memilih audiens tertentu yang Anda ingin dapat melihat API. Anda dapat mengelola visibilitas audiens nanti, seperti yang dijelaskan di Mengelola visibilitas API.
   Gambar tampilan	Untuk menampilkan gambar pada kartu API di halaman APIs, klik Pilih gambar. Di dialog Pilih gambar, pilih salah satu gambar yang ada, unggah gambar baru, atau berikan URL gambar eksternal, lalu klik Select. Melihat pratinjau thumbnail API lalu klik Select. Anda dapat menambahkan gambar nanti, seperti yang dijelaskan di Mengelola image untuk kartu API. Saat menentukan URL gambar eksternal, gambar tidak akan diunggah ke aset; Selain itu, pemuatan gambar di portal terintegrasi akan bergantung pada ketersediaannya, yang mungkin diblokir atau dibatasi oleh kebijakan keamanan konten kami.
   Kategori	Tambahkan kategori yang akan diberi tag dengan API untuk mengaktifkan developer aplikasi Anda untuk menemukan API terkait pada halaman API. Kepada mengidentifikasi kategori: Pilih kategori dari menu drop-down. Tambahkan kategori baru dengan mengetik namanya, lalu menekan Enter. Kategori baru ditambahkan ke halaman Kategori dan dibuat yang tersedia saat menambahkan atau mengedit API lain.

7. Klik Simpan.

curl

Untuk menambahkan API ke portal menggunakan organizations.sites.apidocs.create:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• TITLE dengan judul tampilan. Contoh, Hello World 2.
• DESCRIPTION dengan deskripsi tampilan. Contoh, Simple hello world example.
• ANON_TRUE_OR_FALSE dengan true atau false (default), dengan true memungkinkan akses pengguna anonim. Setelan ini diabaikan jika Anda telah mendaftar di rilis beta fitur pengelolaan audiens.
• IMAGE_URL dengan URL gambar 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 diblokir atau dibatasi oleh kebijakan keamanan konten.
• CALLBACK_TRUE_OR_FALSE dengan true atau false (default), dengan true mengharuskan pengguna portal untuk memasukkan URL saat mengelola aplikasi.

• CATEGORY_ID dengan ID kategori. Contoh, bf6505eb-2a0f-47af-a00a-ded40ac72960. Pisahkan beberapa ID kategori dengan koma. Dapatkan ID kategori dengan mencantumkan kategori API perintah.

  Catatan: Anda harus sudah memiliki kategori untuk menambahkannya di sini. Lihat Menambahkan kategori dan Menjelajahi kategori untuk mendapatkan petunjuk.

• PUBLISHED_TRUE_OR_FALSE dengan true atau false (default), dengan true menunjukkan API tersedia untuk publik.

• API_PRODUCT dengan nama produk API. Contoh, Hello World 2.

Payload respons:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Dengan keterangan:

• modified: Waktu item katalog terakhir diubah dalam milidetik sejak epoch. Contoh, 1698165480000.
• id: ID item katalog. Contoh, 399668.

Mengedit API

Setelah menambahkan API, gunakan konsol atau panggilan API untuk melakukan pengeditan.

Bagian ini memberikan contoh terperinci langkah-langkah yang harus dilakukan untuk memodifikasi yang ada di portal Anda.

Lihat bagian berikutnya untuk setelan modifikasi spesifik.

Konsol

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik Edit.
5. Di bagian Detail API, lakukan perubahan apa pun. Lihat deskripsi di bagian Add an API.
6. Klik Simpan.

curl

Setelah menambahkan API, gunakan organizations.sites.apidocs.update untuk mengedit.

Perhatian: Panggilan API organizations.sites.apidocs.update mereset kolom yang dapat diubah ke nilai default jika tidak ditentukan.

Contoh ini memandu Anda melakukan langkah-langkah yang diperlukan untuk mengubah status API Anda di portal dari true menjadi false. Anda dapat mengubah lebih dari satu setelan dalam satu panggilan API jika diperlukan.

1. Dapatkan daftar API di portal Anda menggunakan organizations.sites.apidocs/list untuk menemukan ID id yang mengidentifikasi setiap API secara unik:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

   Ganti kode berikut:

   • ORG_NAME dengan nama organisasi. Contoh, my-org.
   • SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.

   Payload respons:

   {
     "status": "success",
     "message": "one page of apidocs returned",
     "requestId": "1167960478",
     "data": [
       {
         "siteId": "my-org-myportal",
         "title": "Hello New World",
         "description": "Simple hello new world example",
         "specId": "hellowworld",
         "modified": "1695841621000",
         "anonAllowed": true,
         "imageUrl": "/files/camper1.jpg?v=1695841491415",
         "id": "381054",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
           "61c1014c-89c9-40e6-be3c-69cca3505620"
         ],
         "published": true,
         "apiProductName": "Hello New World"
       },
       {
         "siteId": "my-org-myportal",
         "title": "mock-product",
         "description": "Mock product",
         "specId": "apigee spec",
         "modified": "1698956849000",
         "anonAllowed": true,
         "id": "399638",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
         ],
         "published": true,
         "apiProductName": "mock-product"
       },
       {
         "siteId": "my-org-myportal",
         "title": "Hello World 2",
         "description": "Simple hello world example",
         "specId": "hello-new-world",
         "modified": "1698950207000",
         "anonAllowed": true,
         "imageUrl": "/files/book-tree.jpg?v=1698165437881",
         "id": "399668",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
           "61c1014c-89c9-40e6-be3c-69cca3505620"
         ],
         "published": true,
         "apiProductName": "Hello World 2"
       }
     ]
   }

   Dengan keterangan:

   • modified: Waktu item katalog terakhir diubah dalam milidetik sejak epoch. Contoh, 1698165480000.
   • id: ID item katalog. Contoh, 399668.

2. Gunakan panggilan organizations.sites.apidocs.get untuk menampilkan nilai saat ini untuk API spesifik:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

   Ganti kode berikut:

   • ORG_NAME dengan nama organisasi. Contoh, my-org.
   • SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
   • API_DOC dengan id dokumen yang dihasilkan. Contohnya, 399668. Gunakan perintah list API docs untuk menemukan nilai ini.

   Payload respons:

   {
     "status": "success",
     "message": "apidoc returned",
     "requestId": "2072952505",
     "data": {
       "siteId": "my-org-myportal",
       "title": "Hello World 2",
       "description": "Simple hello world example",
       "specId": "hello-new-world",
       "modified": "1698950207000",
       "anonAllowed": true,
       "imageUrl": "/files/book-tree.jpg?v=1698165437881",
       "id": "399668",
       "categoryIds": [
         "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
         "61c1014c-89c9-40e6-be3c-69cca3505620"
       ],
       "published": true,
       "apiProductName": "Hello World 2"
     }
   }

3. Sertakan nilai yang dapat diubah yang ingin Anda pertahankan di organizations.sites.apidocs.update, dan mengubah nilai yang Anda inginkan berubah. Jika Anda menghilangkan baris, setelan default akan digunakan. Untuk ini misalnya, ubah setelan published dari true menjadi false:

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": "IMAGE_URL",
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": false,
           "apiProductName": "API_PRODUCT",
        }'
   

   Ganti kode berikut:

   • TITLE dengan judul tampilan. Contoh, Hello World 2.
   • DESCRIPTION dengan deskripsi tampilan. Contoh, Simple hello world example.
   • ANON_TRUE_OR_FALSE dengan true atau false (default), dengan true memungkinkan akses pengguna anonim. Setelan ini diabaikan jika Anda telah mendaftar di rilis beta fitur pengelolaan audiens.
   • IMAGE_URL dengan URL gambar 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 diblokir atau dibatasi oleh kebijakan keamanan konten.
   • CALLBACK_TRUE_OR_FALSE dengan true atau false (default), dengan true mengharuskan pengguna portal untuk memasukkan URL saat mengelola aplikasi.
   • CATEGORY_ID dengan ID kategori. Contoh, bf6505eb-2a0f-47af-a00a-ded40ac72960. Pisahkan beberapa ID kategori dengan koma. Dapatkan ID kategori dengan mencantumkan kategori API perintah.
   • API_PRODUCT dengan nama produk API. Contoh, Hello World 2.

   Payload respons:

   {
     "status": "success",
     "message": "ApiDoc updated",
     "requestId": "197181831",
     "data": {
       "siteId": "my-org-myportal",
       "title": "Hello World 2",
       "description": "Simple hello world example.",
       "modified": "1698884328000",
       "anonAllowed": true,
       "imageUrl": "/files/book-tree.jpg",
       "id": "408567",
       "requireCallbackUrl": true,
       "categoryIds": [
         "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
         "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
       ],
       "published": PUBLISHED_TRUE_OR_FALSE,
       "apiProductName": "Hello World 2"
     }
   }
   

Memublikasikan atau membatalkan publikasi API

Publikasi adalah proses penyediaan API Anda bagi developer aplikasi untuk digunakan.

Untuk memublikasikan atau membatalkan publikasi API di portal Anda:

Konsol

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

curl

Perhatian: Panggilan API organizations.sites.apidocs.update mereset kolom yang dapat diubah ke nilai default jika tidak ditentukan.

Sertakan salah satu dari hal berikut dalam update hubungi:

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

Untuk mengedit API:

1. Gunakan panggilan organizations.sites.apidocs.get untuk menampilkan nilai saat ini:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Menggunakan organizations.sites.apidocs.update untuk mengedit API. Sertakan nilai yang dapat diubah yang ingin Anda pertahankan dan ubah nilai yang ingin diubah. Jika Anda menghilangkan setelan yang dapat diubah, yang digunakan adalah nilai default.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Lihat Mengedit API untuk contoh detail langkah-langkah, variabel, dan payload ditampilkan.

Mengelola visibilitas API

Kelola visibilitas API di portal Anda dengan mengizinkan akses ke:

• Publik (terlihat oleh siapa saja)
• Pengguna terautentikasi

• Audiens yang dipilih (jika Anda memiliki terdaftar dalam rilis beta fitur pengelolaan audiens)

  Catatan: Jika Anda menyetel visibilitas ke Pengguna yang diautentikasi atau Audiens yang dipilih, API tidak akan diindeks oleh mesin telusur.

Untuk mengelola visibilitas API di portal Anda:

Konsol

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

5. Pilih setelan visibilitas. Jika Anda memiliki terdaftar dalam rilis beta fitur audiens, pilih salah satu opsi berikut di bagian Visibilitas API:

   • 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 dapat melihat halaman. Lihat Mengelola audiens untuk portal Anda.

   Jika tidak, pilih salah satu opsi berikut di bagian Audiens:

   • Pengguna anonim untuk mengizinkan semua pengguna melihat halaman.
   • Pengguna terdaftar berarti hanya pengguna terdaftar yang diizinkan melihat halaman.

6. Klik Kirim.

curl

Perhatian: Panggilan API organizations.sites.apidocs.update mereset kolom yang dapat diubah ke nilai default jika tidak ditentukan.

Jika Anda memiliki terdaftar dalam rilis beta fitur pengelolaan audiens, gunakan konsol untuk mengelola audiens.

Jika Anda belum terdaftar dalam fitur pengelolaan audiens, visibilitas akan dikelola menggunakan anonAllowed.

Sertakan salah satu dari hal berikut dalam update hubungi:

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

Untuk mengedit API:

1. Gunakan panggilan organizations.sites.apidocs.get untuk menampilkan nilai saat ini:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Menggunakan organizations.sites.apidocs.update untuk mengedit API. Sertakan nilai yang dapat diubah yang ingin Anda pertahankan dan ubah nilai yang ingin diubah. Jika Anda menghilangkan setelan yang dapat diubah, yang digunakan adalah nilai default.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Lihat Mengedit API untuk contoh detail langkah-langkah, variabel, dan payload ditampilkan.

Mengelola URL callback untuk API

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

Untuk mengelola URL callback untuk API:

Konsol

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik Edit.
5. Di bagian Detail API, pilih atau hapus Mewajibkan developer untuk menentukan URL callback untuk menentukan bahwa URL callback wajib atau tidak diperlukan.
6. Klik Simpan.

curl

Perhatian: Panggilan API organizations.sites.apidocs.update mereset kolom yang dapat diubah ke nilai default jika tidak ditentukan.

Sertakan salah satu dari hal berikut dalam update hubungi:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

Untuk mengedit API:

1. Gunakan panggilan organizations.sites.apidocs.get untuk menampilkan nilai saat ini:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Menggunakan organizations.sites.apidocs.update untuk mengedit API. Sertakan nilai yang dapat diubah yang ingin Anda pertahankan dan ubah nilai yang ingin diubah. Jika Anda menghilangkan setelan yang dapat diubah, yang digunakan adalah nilai default.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Lihat Mengedit API untuk contoh detail langkah-langkah, variabel, dan payload ditampilkan.

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:

Konsol

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

5. Di bagian Detail API:

   • Klik Pilih gambar untuk menentukan gambar jika tidak ada gambar dipilih.
   • Klik Ubah gambar untuk menentukan 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.

curl

Perhatian: Panggilan API organizations.sites.apidocs.update mereset kolom yang dapat diubah ke nilai default jika tidak ditentukan.

Sertakan informasi berikut dalam update hubungi:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

Untuk mengedit API:

1. Gunakan panggilan organizations.sites.apidocs.get untuk menampilkan nilai saat ini:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Menggunakan organizations.sites.apidocs.update untuk mengedit API. Sertakan nilai yang dapat diubah yang ingin Anda pertahankan dan ubah nilai yang ingin diubah. Jika Anda menghilangkan setelan yang dapat diubah, yang digunakan adalah nilai default.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Lihat Mengedit API untuk contoh detail langkah-langkah, variabel, dan payload ditampilkan.

Memberi tag pada API menggunakan kategori

Penggunaan kategori membantu developer aplikasi menemukan API terkait. Lihat juga Mengelola kategori.

Untuk memberi tag pada API dengan kategori:

Konsol

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

5. Klik kolom Kategori dan lakukan salah satu langkah berikut:

   • Pilih kategori dari menu drop-down.
   • Tambahkan kategori baru dengan mengetik namanya, lalu menekan Enter. Yang baru kategori akan ditambahkan ke halaman Kategori dan tersedia saat menambahkan atau mengedit API lainnya.

6. Ulangi untuk memberi tag pada API dengan kategori lainnya.

7. Klik Simpan.

curl

Perhatian: Panggilan API organizations.sites.apidocs.update mereset kolom yang dapat diubah ke nilai default jika tidak ditentukan.

Sertakan informasi berikut dalam update hubungi:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Gunakan kategori daftar untuk mendapatkan nomor ID kategori.

Untuk mengedit API:

1. Gunakan panggilan organizations.sites.apidocs.get untuk menampilkan nilai saat ini:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Menggunakan organizations.sites.apidocs.update untuk mengedit API. Sertakan nilai yang dapat diubah yang ingin Anda pertahankan dan ubah nilai yang ingin diubah. Jika Anda menghilangkan setelan yang dapat diubah, yang digunakan adalah nilai default.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Lihat Mengedit API untuk contoh detail langkah-langkah, variabel, dan payload ditampilkan.

Mengedit judul dan deskripsi tampilan

Untuk mengedit judul dan deskripsi tampilan:

Konsol

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

curl

Perhatian: Panggilan API organizations.sites.apidocs.update mereset kolom yang dapat diubah ke nilai default jika tidak ditentukan.

Sertakan informasi berikut dalam update hubungi:

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

Untuk mengedit API:

1. Gunakan panggilan organizations.sites.apidocs.get untuk menampilkan nilai saat ini:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Menggunakan organizations.sites.apidocs.update untuk mengedit API. Sertakan nilai yang dapat diubah yang ingin Anda pertahankan dan ubah nilai yang ingin diubah. Jika Anda menghilangkan setelan yang dapat diubah, yang digunakan adalah nilai default.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Lihat Mengedit API untuk contoh detail langkah-langkah, variabel, dan payload ditampilkan.

Menghapus API

Untuk menghapus API dari portal Anda:

Konsol

1. Akses katalog API.
2. Pilih tab APIs, jika belum dipilih.
3. Posisikan kursor Anda di atas API dalam daftar untuk menampilkan menu tindakan.
4. Klik Delete.

curl

Untuk menghapus API dari portal menggunakan organizations.sites.apidocs.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• API_DOC dengan id dokumen yang dihasilkan. Contohnya, 399668. Gunakan perintah list API docs untuk menemukan nilai ini.

Payload respons:

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

Mengelola dokumentasi API

Bagian berikut menjelaskan cara mengupdate, mendownload, atau menghapus API dokumentasi layanan.

Memperbarui dokumentasi API

Setelah memublikasikan API, Anda dapat mengunggah versi baru dari Dokumen OpenAPI atau GraphQL.

Untuk mengupload dokumentasi API versi lain:

Konsol

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik Edit.
5. Di panel API documentation, pilih salah satu opsi berikut:
   • Dokumen OpenAPI
   • Skema GraphQL
6. Klik Pilih Dokumen, lalu pilih versi terbaru dokumen.
7. Untuk GraphQL, tentukan URL Endpoint.
8. Klik Simpan.

curl

Untuk mengupdate konten dokumentasi OpenAPI atau GraphQL menggunakan organizations.sites.apidocs.updateDocumentation:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• API_DOC dengan id dokumen yang dihasilkan. Contohnya, 399668. Gunakan perintah list API docs untuk menemukan nilai ini.
• DISPLAY_NAME dengan nama tampilan dokumentasi API. Contoh, Hello World 2.
• CONTENTS dengan string konten API yang dienkode base64 dokumentasi layanan. Sebagian besar lingkungan pengembangan berisi base64, atau ada banyak alat konversi online.

Payload respons:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• API_DOC dengan id dokumen yang dihasilkan. Contohnya, 399668. Gunakan perintah list API docs untuk menemukan nilai ini.
• DISPLAY_NAME dengan nama tampilan dokumentasi API. Contoh, Hello World 2.
• ENDPOINT_URI dengan nama domain URI endpoint Anda. Contoh, https://demo.google.com/graphql.
• CONTENTS dengan string konten API yang dienkode base64 dokumentasi layanan. Sebagian besar lingkungan pengembangan berisi base64, atau ada banyak alat konversi online.

Payload respons:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

Catatan: Konten spesifikasi atau skema tidak diisi pada respons. Gunakan organizations.sites.apidocs.getDocumentation untuk mengambil kontennya.

Dokumentasi referensi API dirender dari dokumen dan ditambahkan ke Halaman API dari portal live.

Download dokumentasi API

Setelah memublikasikan API, Anda dapat mendownload Dokumentasi referensi OpenAPI atau GraphQL yang dipublikasikan di portal Anda.

Untuk mendownload dokumentasi API menggunakan organizations.sites.apidocs.getDocumentation:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.

• API_DOC dengan id dokumen yang dihasilkan. Contohnya, 399668. Gunakan perintah list API docs untuk menemukan nilai ini.

  Payload respons:

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

Dengan keterangan:

contents: String konten dokumentasi API yang dienkode dengan base64.

Tips: Pengguna portal resmi dapat mendownload dokumentasi API dari portal:

1. Buka portal.
2. Klik API di menu navigasi atas. Halaman APIs ditampilkan ditampilkan.
3. Klik kartu API untuk melihat dokumentasi referensi API. API dokumentasi referensi akan ditampilkan.
4. Klik Download spesifikasi.

Menghapus dokumentasi API

Untuk menghapus dokumentasi API:

Konsol

1. Akses katalog API.
2. Klik tab APIs jika belum dipilih.
3. Klik di baris API yang ingin Anda edit.
4. Klik Edit.
5. Di panel API documentation, pilih No documentation.
6. Klik Simpan.

curl

Untuk menghapus konten dokumen API menggunakan API, hapus setelan yang ada dengan mengirimkan isi permintaan kosong.

Untuk mengirim isi permintaan kosong dan menghapus konten yang ada menggunakan organizations.sites.apidocs.updateDocumentation:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• API_DOC dengan id dokumen yang dihasilkan. Contohnya, 399668. Gunakan perintah list API docs untuk menemukan nilai ini.

Payload respons:

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

Kelola kategori

Beri tag pada API menggunakan kategori agar developer aplikasi dapat menemukan info terkait API di halaman API dari portal live. Tambahkan dan kelola kategori, seperti yang dijelaskan di bawah bagian.

Jelajahi Kategori

Gunakan konsol atau perintah curl untuk melihat kategori.

Konsol

Untuk melihat halaman Kategori:

1. Pilih Publikasikan > Portal dan pilih portal Anda.
2. Klik API Catalog di halaman beranda portal.
   Atau, Anda dapat memilih Katalog API di menu drop-down portal di 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:

   • Melihat kategori dan API tempat kategori tersebut diberi tag
   • Menambahkan kategori
   • Mengedit kategori
   • Menghapus kategori
   • Kelola API yang dipublikasikan ke portal Anda. Lihat Jelajahi API.

curl

Untuk mencantumkan kategori menggunakan organizations.sites.apicategories.list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.

Payload respons:

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

Dengan keterangan:

• id: ID item kategori. Contoh, 61c1014c-89c9-40e6-be3c-69cca3505620.

Tambahkan kategori

Untuk menambahkan kategori:

Konsol

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

curl

Untuk menambahkan kategori menggunakan organizations.sites.apicategories.create:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• CATEGORY_NAME dengan nama kategori. Contoh, demo-backend.

Payload respons:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

Edit kategori

Untuk mengedit kategori:

Konsol

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

curl

Untuk mengedit kategori menggunakan organizations.sites.apicategories.patch:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• CATEGORY_ID dengan ID kategori. Contoh, bf6505eb-2a0f-47af-a00a-ded40ac72960. Dapatkan ID kategori dengan mencantumkan kategori API perintah.
• CATEGORY_NAME dengan nama kategori. Contoh, demo-backend.

Payload respons:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

Menghapus kategori

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

Untuk menghapus kategori:

Konsol

1. Akses halaman Kategori.
2. Posisikan kursor di atas kategori yang ingin Anda edit untuk menampilkan menu tindakan.
3. Klik Delete.
4. Klik Hapus untuk mengonfirmasi.

curl

Untuk menghapus kategori menggunakan organizations.sites.apicategories.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

Ganti kode berikut:

• ORG_NAME dengan nama organisasi. Contoh, my-org.
• SITE_ID dengan nama portal, dalam formulir ORG_NAME-PORTAL_NAME, dengan ORG_NAME adalah nama organisasi dan PORTAL_NAME adalah nama portal yang dikonversi menjadi huruf kecil semua, serta menghapus spasi dan tanda hubung. Contoh, my-org-myportal.
• CATEGORY_ID dengan ID kategori. Contoh, bf6505eb-2a0f-47af-a00a-ded40ac72960. Dapatkan ID kategori dengan mencantumkan kategori API perintah.

Payload respons:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

Memecahkan masalah terkait API yang dipublikasikan

Catatan: Bagian ini hanya berlaku untuk dokumentasi referensi SmartDocs API, dibuat menggunakan dokumen OpenAPI.

Bagian berikut memberikan informasi untuk membantu Anda memecahkan masalah error pada 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 adalah dikembalikan, pertimbangkan kemungkinan penyebab dan penyelesaiannya:

• Untuk error konten campuran, error tersebut mungkin disebabkan oleh masalah yang diketahui terkait swagger-ui. Salah satu solusi yang mungkin adalah memastikan bahwa Anda menentukan HTTPS sebelum HTTP di 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 panel Coba API ini.

Error: Kolom header permintaan tidak diizinkan

Saat menggunakan Coba API ini, jika Anda menerima Request header field not allowed mirip dengan contoh berikut, Anda mungkin perlu memperbarui header didukung dalam kebijakan CORS. Contoh:

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 Anda, sebagai dijelaskan dalam Melampirkan kebijakan Tambahkan CORS ke proxy API baru.

Error: Akses ditolak saat memanggil proxy API menggunakan OAuth 2.0

Kebijakan OAuthV2 Konsol Google Cloud menampilkan respons token yang berisi properti yang tidak sesuai dengan RFC. Misalnya, kebijakan itu akan mengembalikan 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.