API tasarımına genel bakış

Apigee Edge belgelerini görüntülüyorsunuz.
Git: Apigee X belgeleri. bilgi

Tasarım aşamasında, API'nize ilişkin gereksinimleri tanımlarsınız. API tasarımcısı olarak tüketicilere sunmak istediğiniz hizmetleri planlar ve bu hizmetlere erişmek için API'ler tasarlarsınız. API gereksinimlerinizi öğrenmek için aşağıdaki belgelerden birini oluşturursunuz:

  • Bir OpenAPI dokümanı
  • GraphQL şeması

Aşağıdaki bölümlerde, OpenAPI ve GraphQL belgeleri ve API'nizin yaşam döngüsünde oynadıkları rol hakkında daha fazla bilgi verilmektedir. İki API tasarım seçeneğinin karşılaştırması için bu blog yayınındaki REST ve GraphQL karşılaştırmalarına göz atın.

OpenAPI Spesifikasyonu nedir?


"OpenAPI Initiative (OAI), Swagger Spesifikasyonu'na dayalı olarak satıcıdan bağımsız bir API Açıklama Biçimi oluşturmaya, geliştirmeye ve tanıtmaya odaklanıyor." OpenAPI Initiative hakkında daha fazla bilgi için https://openapis.org adresini ziyaret edin.

OpenAPI dokümanlarında, RESTful API'yi tanımlamak için standart bir biçim kullanılır. JSON veya YAML biçiminde yazılan OpenAPI belgeleri makine tarafından okunabilir ancak aynı zamanda kullanıcılar tarafından da kolayca okunup anlaşılır. OpenAPI Spesifikasyonu, bir API'nin temel yolu, yolları ve fiilleri, üstbilgileri, sorgu parametreleri, içerik türleri, yanıt modelleri ve daha fazlası gibi öğelerinin resmi açıklamasını sağlar. Ayrıca OpenAPI belgeleri, API belgelerini oluşturmak için yaygın olarak kullanılır.

Bir OpenAPI belgesinden Apigee'nin basit hello dünya örneğini açıklayan bir parçayı burada bulabilirsiniz. Daha fazla bilgi için şurada OpenAPI Spesifikasyonunu görüntüleyin: GitHub'a gidin.

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

OpenAPI spesifikasyonları hakkında birçok mükemmel bilgi kaynağı vardır. Genel bakışları, blogları ve OpenAPI Spesifikasyonu bağlantılarını bulabileceğiniz OpenAPI Initiative sitesi iyi bir başlangıç noktasıdır. Şema öğelerinin ve veri türlerinin ayrıntılı açıklamaları için Spesifikasyon'a bakın.

OpenAPI spesifikasyonu deposundan indirebileceğiniz çeşitli JSON ve YAML örnek OpenAPI belgeleri vardır.

GraphQL şeması nedir?

GraphQL şeması, bir istemcinin sorgulaması için API'nizde bulunan verileri açıklar.

GraphQL'i kullanmanın avantajları arasında şunlar vardır:

  • Tek bir uç nokta, belirli bir işlem için tüm alanlara erişim sağlar
  • Şema Tanımlama Dili adı verilen güçlü sorgu dili, verilerin aşırı veya az getirilmesini önleyerek ihtiyacınız olan verilere tam olarak erişmenizi sağlar.
  • Sorguların paralel olarak işlenmesi

GraphQL hakkında daha fazla bilgi için graphql.org adresine bakın.

Aşağıda, veri giriş noktasını (Sorgu türü), kullanılabilir yazma işlemlerini (Dönüşüm türü) ve veri türlerini tanımlayan bir GraphQL şeması örneği sunulmaktadır.

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!
}

İhtiyacınız olan tam verileri bir JSON yükü olarak döndürmek için GraphQL şemasını sorgulayabilirsiniz.

GraphQL sorgusu ve sonuçları

Bir dokümanı değiştirirsem ne olur?

Her OpenAPI veya GraphQL dokümanı, API yaşam döngüsü boyunca doğru bilgi kaynağı olarak kullanılır. Aynı belge, geliştirmeden yayınlamaya ve izlemeye kadar API yaşam döngüsünün her aşamasında kullanılır.

Bir dokümanı düzenlediğinizde veya sildiğinizde bu işlemler aşağıdakileri etkiler:

  • Bir dokümanı düzenlerseniz API proxy'si ve bu belgenin kaynaklarını açığa çıkaran tüm API ürünleri dahil olmak üzere ilgili yapıları manuel olarak düzenlemeniz ve dokümanda uygulanan değişiklikleri yansıtmak için API referans belgelerini yeniden oluşturmanız gerekir.
  • Bir belgeyi silerseniz API proxy'si de dahil olmak üzere ilgili yapıları manuel olarak silmeniz, ilgili kaynakları silmek için API ürünlerini düzenlemeniz ve belge ile kaynaklarının kaldırılmasını yansıtacak şekilde API referans belgelerini yeniden oluşturmanız gerekir.

Bir OpenAPI belgesinden API proxy'si oluşturduğumda ne olur?

Edge'de, OpenAPI belgelerinizden API proxy'lerinizi oluşturabilirsiniz. Yalnızca birkaç tıklamayla otomatik olarak oluşturulan yollar, parametreler, koşullu akışlar ve hedef uç noktalarını içeren bir API proxy'sine sahip olursunuz. Ardından OAuth güvenliği, hız sınırlaması ve önbelleğe alma gibi özellikler ekleyebilirsiniz.

Aşağıdaki bölümlerde açıklandığı gibi, OpenAPI belgesinden API proxy'si oluşturabilirsiniz:

API'nizi yayınladığınızda API referans belgelerini oluşturmak için OpenAPI belgesinin anlık görüntüsünü alırsınız. Bu anlık görüntü, spesifikasyon deposundaki açıklama dokümanının belirli bir düzeltmesini gösterir.