API tasarımına genel bakış

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Tasarım aşamasında API'nizle ilgili şartları 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 belirlemek için aşağıdaki belgelerden birini oluşturursunuz:

  • OpenAPI dokümanı
  • GraphQL şeması

Aşağıdaki bölümlerde, OpenAPI ve GraphQL belgeleri ile API'nizin yaşam döngüsündeki rolleri hakkında daha fazla bilgi verilmektedir. İki API tasarım seçeneğinin karşılaştırması için bu blog yayınında REST ve GraphQL karşılaştırmasına bakın.

OpenAPI Spesifikasyonu nedir?


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

OpenAPI belgesi, RESTful API'yi açıklamak için standart bir biçim kullanır. JSON veya YAML biçiminde yazılan OpenAPI belgesi, makine tarafından okunabilir ancak insanlar tarafından da kolayca okunup anlaşılabilir. OpenAPI Spesifikasyonu, bir API'nin temel yolu, yolları ve fiilleri, başlıkları, sorgu parametreleri, içerik türleri, yanıt modelleri gibi öğelerinin resmi olarak açıklanmasını sağlar. Ayrıca, API belgelerini oluşturmak için genellikle bir OpenAPI belgesi kullanılır.

Aşağıda, Apigee'nin basit "Merhaba Dünya" örneğini açıklayan bir OpenAPI belgesinden alınmış bir parça yer almaktadır. Daha fazla bilgi için GitHub'daki OpenAPI Spesifikasyonu'na göz atın.

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. Başlamak için iyi bir yer olan OpenAPI Initiative sitesinde genel bakışlar, bloglar ve OpenAPI Spesifikasyonu'na bağlantılar bulabilirsiniz. Şema öğelerinin ve veri türlerinin ayrıntılı açıklamaları için Spesifikasyon'a bakın.

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

GraphQL şeması nedir?

GraphQL şeması, bir istemcinin sorgulayabileceği API'nizdeki verileri açıklar.

GraphQL kullanmanın avantajları:

  • 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, tam olarak ihtiyacınız olan verilere erişmenizi sağlayarak verilerin aşırı veya yetersiz getirilmesini önler.
  • Sorgular paralel olarak işlenir.

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 (Değişiklik türü) ve veri türlerini tanımlayan bir GraphQL şeması örneği verilmiştir.

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 verileri JSON yükü olarak döndürmek için GraphQL şemasını sorgulayabilirsiniz.

GraphQL sorgusu ve sonuçları

Bir belgeyi değiştirirsem ne olur?

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

Bir belgeyi düzenlediğinizde veya sildiğinizde bu durum ilerleyen zamanlarda şu etkileri gösterir:

  • Bir dokümanı düzenlerseniz API proxy'si ve kaynaklarını kullanıma sunan 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 dokümanı 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 dokümanın ve kaynaklarının kaldırılmasını yansıtmak için API referans belgelerini yeniden oluşturmanız gerekir.

OpenAPI dokümanından API proxy'si oluşturduğumda ne olur?

Edge'de, OpenAPI dokümanlarınızdan API proxy'leri oluşturabilirsiniz. Yalnızca birkaç tıklamayla yollar, parametreler, koşullu akışlar ve hedef uç noktalar otomatik olarak oluşturulmuş bir API proxy'sine sahip olursunuz. Ardından, OAuth güvenliği, sıklık sınırlama ve önbelleğe alma gibi özellikler ekleyebilirsiniz.

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

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