Ringkasan desain API

Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.

Pada fase Desain, Anda menentukan persyaratan untuk API Anda. Sebagai desainer API, Anda merencanakan layanan yang ingin Anda tunjukkan kepada konsumen, dan mendesain API untuk mengakses layanan tersebut. Anda membuat salah satu dokumen berikut untuk memenuhi persyaratan API Anda:

  • Dokumen OpenAPI
  • Skema GraphQL

Bagian berikut memberikan informasi selengkapnya tentang dokumen OpenAPI dan GraphQL serta perannya dalam siklus proses API. Untuk perbandingan dua opsi desain API, lihat REST dan GraphQL dibandingkan dalam postingan blog ini.

Apa Spesifikasi OpenAPI tersebut?


"OpenAPI Initiative (OAI) berfokus pada pembuatan, pengembangan, dan promosi Format Deskripsi API netral vendor berdasarkan Spesifikasi Swagger." Untuk informasi selengkapnya tentang Inisiatif OpenAPI, lihat https://openapis.org.

Dokumen OpenAPI menggunakan format standar untuk mendeskripsikan RESTful API. Ditulis dalam format JSON atau YAML, dokumen OpenAPI dapat dibaca mesin, tetapi juga mudah dibaca dan dipahami oleh manusia. Spesifikasi OpenAPI memungkinkan deskripsi formal dari elemen API seperti jalur dasarnya, jalur dan kata kerja, header, parameter kueri, jenis konten, model respons, dan banyak lagi. Selain itu, dokumen OpenAPI biasanya digunakan untuk membuat dokumentasi API.

Berikut adalah fragmen dari dokumen OpenAPI yang menjelaskan contoh halo sederhana dari Apigee. Untuk informasi selengkapnya, lihat Spesifikasi OpenAPI di GitHub.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

Tersedia banyak sumber informasi yang sangat bagus tentang Spesifikasi OpenAPI. Tempat yang baik untuk memulai adalah situs OpenAPI Initiative, tempat Anda akan menemukan ringkasan, blog, dan link ke Spesifikasi OpenAPI. Lihat Spesifikasi untuk mengetahui deskripsi mendetail tentang elemen skema dan jenis data.

Ada sejumlah dokumen OpenAPI JSON dan YAML yang dapat Anda download dari repositori Spesifikasi OpenAPI.

Apa itu skema GraphQL?

Skema GraphQL menjelaskan data yang tersedia di API Anda untuk dikueri oleh klien.

Manfaat menggunakan GraphQL meliputi:

  • Endpoint tunggal memberikan akses ke semua kolom untuk operasi tertentu
  • Bahasa kueri yang canggih, yang disebut Bahasa Definisi Skema, memungkinkan Anda mengakses data yang dibutuhkan dengan tepat, mencegah pengambilan data yang terlalu banyak atau terlalu sedikit
  • Pemrosesan kueri terjadi secara paralel

Untuk informasi selengkapnya tentang GraphQL, lihat graphql.org.

Berikut ini adalah contoh skema GraphQL yang menentukan titik entri data (jenis Kueri), operasi tulis yang tersedia (jenis Mutasi), dan jenis data.

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

Anda dapat mengkueri skema GraphQL untuk menampilkan data spesifik yang diperlukan sebagai payload JSON.

Kueri dan hasil GraphQL

Apa yang terjadi jika saya mengubah dokumen?

Setiap dokumen OpenAPI atau GraphQL berfungsi sebagai sumber tepercaya di seluruh siklus proses API. Dokumen yang sama digunakan di setiap fase dalam siklus proses API, dari pengembangan hingga publikasi hingga pemantauan.

Saat Anda mengedit atau menghapus dokumen, dokumen tersebut akan terkena dampak negatifnya:

  • Jika mengedit dokumen, Anda harus mengedit artefak terkait secara manual, termasuk proxy API dan produk API apa pun yang mengekspos resource-nya, dan membuat ulang dokumentasi referensi API untuk mencerminkan perubahan yang diterapkan dalam dokumen.
  • Jika Anda menghapus dokumen, Anda harus menghapus artefak terkait secara manual, termasuk proxy API dan mengedit produk API apa pun untuk menghapus resource terkait, dan membuat ulang dokumentasi referensi API untuk mencerminkan penghapusan dokumen dan resource-nya.

Apa yang terjadi jika saya membuat proxy API dari dokumen OpenAPI?

Di Edge, Anda dapat membuat proxy API dari dokumen OpenAPI Anda. Hanya dengan beberapa klik, Anda akan memiliki proxy API dengan jalur, parameter, alur bersyarat, dan endpoint target yang dibuat secara otomatis. Kemudian, Anda dapat menambahkan fitur seperti keamanan OAuth, pembatasan kapasitas, dan caching.

Anda dapat membuat proxy API dari dokumen OpenAPI, seperti yang dijelaskan di bagian berikut:

Saat memublikasikan API, Anda mengambil snapshot dokumen OpenAPI untuk membuat dokumentasi referensi API. Ringkasan tersebut merupakan revisi khusus dari dokumen deskripsi di penyimpanan spesifikasi.