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'nizin şartlarını tanımlarsınız. Bir 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 yakalamak için aşağıdaki belgelerden birini oluşturursunuz:

  • 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 verilmiştir. İki API tasarım seçeneğinin karşılaştırması için bu blog yayınındaki REST ve GraphQL seçeneklerini karşılaştırabilirsiniz.

OpenAPI Spesifikasyonu nedir?


"OpenAPI Initiative (OAI), Swagger Şartnamesini temel alan, tedarikçiden 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 adresine bakın.

OpenAPI dokümanları, bir RESTful API'yi tanımlamak için standart bir biçim kullanır. JSON veya YAML biçiminde yazılan OpenAPI belgeleri hem makine tarafından okunabilir hem de insanlar tarafından kolayca okunup anlaşılabilir. OpenAPI Spesifikasyonu, API'lerin temel yolu, yolları ve fiilleri, başlıkları, sorgu parametreleri, içerik türleri, yanıt modelleri ve daha fazlası gibi öğelerin resmi bir şekilde açıklanmasını sağlar. Ayrıca, API belgeleri oluşturmak için yaygın olarak OpenAPI belgeleri kullanılır.

Apigee'nin basit merhaba dünya örneğini açıklayan OpenAPI belgesinden bir parça aşağıda verilmiştir. Daha fazla bilgi için GitHub'daki OpenAPI Spesifikasyonu'nu inceleyin.

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 Özellikleri hakkında birçok mükemmel bilgi kaynağı mevcuttur. Başlamak için iyi bir yer olan OpenAPI Initiative sitesidir. Burada genel bakışlar, bloglar ve OpenAPI Specification bağlantıları bulabilirsiniz. Şema öğelerinin ve veri türlerinin ayrıntılı açıklamaları için Spesifikasyon bölümüne bakın.

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

GraphQL şeması nedir?

GraphQL şeması bir istemcinin sorgulayabilmesi için API'nizde kullanılabilen verileri açıklar.

GraphQL kullanmanın avantajları şunlardır:

  • Tek bir uç nokta, belirli bir işlem için tüm alanlara erişim sağlar
  • Şema Tanımlama Dili olarak adlandırılan güçlü sorgu dili, tam olarak ihtiyaç duyduğunuz verilere erişmenizi sağlayarak verilerin fazla veya az getirilmesini önler.
  • Sorguların işlenmesi paralel olarak gerçekleşir

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

Aşağıda, veri giriş noktasını (Sorgu türü), kullanılabilir yazma işlemlerini (Değişim 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!
}

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

GraphQL sorgusu ve sonuçları

Bir dokümanda değişiklik yaparsam ne olur?

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

Bir dokümanı düzenlediğinizde veya sildiğinizde bu durum ilerleyen aşamalarda da etkiler:

  • Bir dokümanı düzenlerseniz API proxy'si ve kaynaklarını kullanıma sunan API ürünleri de dahil olmak üzere ilgili yapıları manuel olarak düzenlemeniz ve API referans dokümanlarını, dokümanda uygulanan değişiklikleri yansıtacak şekilde yeniden oluşturmanız gerekir.
  • Bir belgeyi silerseniz API proxy'si dahil ilgili yapıları manuel olarak silmeniz ve ilgili kaynakları silmek için API ürünlerini düzenlemeniz, ayrıca API referans dokümanlarını belge ve kaynakların kaldırıldığını yansıtacak şekilde yeniden oluşturmanız gerekir.

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

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

Aşağıdaki bölümlerde açıklandığı gibi, OpenAPI dokümanından 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 belgesinin belirli bir düzeltmesini temsil eder.