REST, GraphQL ve gRPC ile Çok Protokollü API Nasıl Oluşturulur?

Özet

İş mantığını protokol katmanlarından ayırarak çok protokollü API'lar oluşturun. Paylaşılan bir etki alanı katmanı oluşturun, ardından üzerine REST, GraphQL ve gRPC adaptörleri ekleyin. Modern PetstoreAPI, bu mimariyi her üç protokolde de tutarlı veri modelleriyle sergiliyor.

Giriş

API'niz web istemcilerine, mobil uygulamalara ve dahili mikro hizmetlere hizmet eder. Web istemcileri basitlik için REST'i tercih eder. Mobil uygulamalar veri transferini azaltmak için GraphQL'i ister. Mikro hizmetler performans için gRPC'yi ister. Üç ayrı API mi oluşturursunuz?

Hayır. Üç protokol katmanına sahip tek bir API oluşturursunuz. İş mantığı aynı kalır. Yalnızca protokol adaptörleri değişir. Bu, çok protokollü API mimarisidir.

Modern PetstoreAPI, paylaşılan bir çekirdekten REST, GraphQL ve gRPC'yi uygular. Aynı evcil hayvan dükkanı mantığı, tutarlı davranışla her üç protokole de hizmet eder.

💡

Çok protokollü API'lar oluşturuyor veya test ediyorsanız, Apidog tek bir araçta REST, GraphQL ve gRPC testini destekler. Tüm protokollerin tutarlı veri döndürdüğünü doğrulayabilir ve protokoller arası iş akışlarını test edebilirsiniz.

düğme

Bu rehberde, Modern PetstoreAPI'yi referans alarak çok protokollü API'lar tasarlamayı, protokol katmanlarını uygulamayı ve protokoller arasında tutarlılığı sağlamayı öğreneceksiniz.

Çok Protokollü Mimari

Çok protokollü API'lar endişeleri katmanlara ayırır.

Katmanlı Mimari

┌─────────────────────────────────────────┐
│  Protocol Layer (REST/GraphQL/gRPC)     │
├─────────────────────────────────────────┤
│  Application Layer (Use Cases)          │
├─────────────────────────────────────────┤
│  Domain Layer (Business Logic)          │
├─────────────────────────────────────────┤
│  Data Layer (Database, Cache)           │
└─────────────────────────────────────────┘

Protokol Katmanı: HTTP, GraphQL sorguları, gRPC çağrılarını yönetir Uygulama Katmanı: Kullanım durumlarını (evcil hayvan oluşturma, sipariş verme) düzenler Etki Alanı Katmanı: İş kuralları (doğrulama, hesaplamalar) Veri Katmanı: Kalıcılık (veritabanı, önbellek)

Temel İlkeler

1. Protokolden bağımsız çekirdek

İş mantığı HTTP, GraphQL veya gRPC hakkında bilgi sahibi değildir. Etki alanı nesneleriyle çalışır.

2. İnce protokol adaptörleri

Protokol katmanları, protokol formatları ile etki alanı nesneleri arasında çeviri yapar. İş mantığı içermezler.

3. Paylaşılan veri modelleri

Tüm protokoller dahili olarak aynı etki alanı modellerini kullanır, bu da tutarlılığı sağlar.

4. Bağımsız dağıtım

Gerektiğinde her protokol ayrı ayrı dağıtılabilir.

Paylaşılan Etki Alanı Katmanı

Etki alanı katmanı, tüm protokollerde paylaşılan iş mantığını içerir.

Etki Alanı Modelleri

// Domain model (protocol-agnostic)
class Pet {
  id: string;
  name: string;
  species: Species;
  status: PetStatus;
  price: number;

  constructor(data: PetData) {
    this.validate(data);
    Object.assign(this, data);
  }

  validate(data: PetData): void {
    if (!data.name || data.name.length < 2) {
      throw new ValidationError('Name must be at least 2 characters');
    }
    if (data.price < 0) {
      throw new ValidationError('Price cannot be negative');
    }
  }

  adopt(userId: string): Order {
    if (this.status !== PetStatus.AVAILABLE) {
      throw new BusinessError('Pet is not available for adoption');
    }
    this.status = PetStatus.ADOPTED;
    return new Order({
      petId: this.id,
      userId,
      total: this.price
    });
  }
}

Bu model REST, GraphQL ve gRPC için çalışır. Doğrulama ve iş kuralları aynıdır.

Kullanım Durumları

// Use case (protocol-agnostic)
class AdoptPetUseCase {
  constructor(
    private petRepository: PetRepository,
    private orderRepository: OrderRepository
  ) {}

  async execute(petId: string, userId: string): Promise<Order> {
    const pet = await this.petRepository.findById(petId);
    if (!pet) {
      throw new NotFoundError('Pet not found');
    }

    const order = pet.adopt(userId);
    await this.petRepository.save(pet);
    await this.orderRepository.save(order);

    return order;
  }
}

Bu kullanım durumu, REST, GraphQL veya gRPC'den çağrılıp çağrılmadığına bakılmaksızın çalışır.

REST Protokol Katmanı

REST katmanı HTTP isteklerini etki alanı işlemlerine çevirir.

REST Controller

// REST adapter
class PetsController {
  constructor(private adoptPetUseCase: AdoptPetUseCase) {}

  async adoptPet(req: Request, res: Response): Promise<void> {
    try {
      const { petId } = req.params;
      const { userId } = req.body;

      const order = await this.adoptPetUseCase.execute(petId, userId);

      res.status(201).json({
        id: order.id,
        petId: order.petId,
        userId: order.userId,
        total: order.total,
        status: order.status
      });
    } catch (error) {
      this.handleError(error, res);
    }
  }

  private handleError(error: Error, res: Response): void {
    if (error instanceof NotFoundError) {
      res.status(404).json({
        type: 'https://petstoreapi.com/errors/not-found',
        title: 'Not Found',
        status: 404,
        detail: error.message
      });
    } else if (error instanceof ValidationError) {
      res.status(400).json({
        type: 'https://petstoreapi.com/errors/validation-error',
        title: 'Validation Error',
        status: 400,
        detail: error.message
      });
    } else {
      res.status(500).json({
        type: 'https://petstoreapi.com/errors/internal-error',
        title: 'Internal Server Error',
        status: 500
      });
    }
  }
}

REST Rotaları

app.post('/v1/pets/:petId/adopt', (req, res) =>
  petsController.adoptPet(req, res)
);

Modern PetstoreAPI REST uç noktaları

GraphQL Protokol Katmanı

GraphQL katmanı GraphQL sorgularını etki alanı işlemlerine çevirir.

GraphQL Şeması

type Pet {
  id: ID!
  name: String!
  species: Species!
  status: PetStatus!
  price: Float!
}

type Order {
  id: ID!
  petId: ID!
  userId: ID!
  total: Float!
  status: OrderStatus!
}

type Mutation {
  adoptPet(petId: ID!, userId: ID!): Order!
}

GraphQL Resolver

// GraphQL adapter
const resolvers = {
  Mutation: {
    adoptPet: async (
      _parent: any,
      args: { petId: string; userId: string },
      context: Context
    ): Promise<Order> => {
      try {
        return await context.adoptPetUseCase.execute(
          args.petId,
          args.userId
        );
      } catch (error) {
        throw new GraphQLError(error.message, {
          extensions: {
            code: error instanceof NotFoundError ? 'NOT_FOUND' :
                  error instanceof ValidationError ? 'BAD_USER_INPUT' :
                  'INTERNAL_SERVER_ERROR'
          }
        });
      }
    }
  }
};

GraphQL İsteği

mutation {
  adoptPet(
    petId: "019b4132-70aa-764f-b315-e2803d882a24"
    userId: "user-123"
  ) {
    id
    total
    status
  }
}

Modern PetstoreAPI GraphQL şeması

gRPC Protokol Katmanı

gRPC katmanı Protocol Buffer mesajlarını etki alanı işlemlerine çevirir.

Protocol Buffer Tanımı

syntax = "proto3";

package petstore.v1;

service PetService {
  rpc AdoptPet(AdoptPetRequest) returns (AdoptPetResponse);
}

message AdoptPetRequest {
  string pet_id = 1;
  string user_id = 2;
}

message AdoptPetResponse {
  string order_id = 1;
  string pet_id = 2;
  string user_id = 3;
  double total = 4;
  string status = 5;
}

gRPC Hizmet Uygulaması

// gRPC adapter
class PetServiceImpl implements IPetService {
  constructor(private adoptPetUseCase: AdoptPetUseCase) {}

  async adoptPet(
    call: ServerUnaryCall<AdoptPetRequest, AdoptPetResponse>,
    callback: sendUnaryData<AdoptPetResponse>
  ): Promise<void> {
    try {
      const { petId, userId } = call.request;

      const order = await this.adoptPetUseCase.execute(petId, userId);

      callback(null, {
        orderId: order.id,
        petId: order.petId,
        userId: order.userId,
        total: order.total,
        status: order.status
      });
    } catch (error) {
      callback({
        code: error instanceof NotFoundError ? status.NOT_FOUND :
              error instanceof ValidationError ? status.INVALID_ARGUMENT :
              status.INTERNAL,
        message: error.message
      });
    }
  }
}

Modern PetstoreAPI gRPC hizmeti

Modern PetstoreAPI Çoklu Protokolü Nasıl Uygular?

Modern PetstoreAPI, gerçek örneklerle çok protokollü mimariyi sergiler.

Mimariye Genel Bakış

Modern PetstoreAPI
├── Domain Layer
│   ├── Pet (entity)
│   ├── Order (entity)
│   └── Use Cases
│       ├── CreatePet
│       ├── AdoptPet
│       └── PlaceOrder
├── REST Layer
│   ├── /v1/pets
│   ├── /v1/orders
│   └── OpenAPI 3.2 spec
├── GraphQL Layer
│   ├── Query resolvers
│   ├── Mutation resolvers
│   └── GraphQL schema
└── gRPC Layer
    ├── PetService
    ├── OrderService
    └── .proto definitions

Tutarlı Veri Modelleri

Tüm protokoller aynı veriyi döndürür:

REST:

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

GraphQL:

{
  "data": {
    "pet": {
      "id": "019b4132-70aa-764f-b315-e2803d882a24",
      "name": "Fluffy",
      "species": "CAT"
    }
  }
}

gRPC:

{
  pet_id: "019b4132-70aa-764f-b315-e2803d882a24"
  name: "Fluffy"
  species: CAT
}

Aynı veri, farklı formatlar.

Paylaşılan Doğrulama

Doğrulama etki alanı katmanında gerçekleşir, bu nedenle tüm protokoller aynı kuralları uygular:

// Domain validation (shared)
if (name.length < 2) {
  throw new ValidationError('Name must be at least 2 characters');
}

REST döndürür:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "status": 400,
  "detail": "Name must be at least 2 characters"
}

GraphQL döndürür:

{
  "errors": [{
    "message": "Name must be at least 2 characters",
    "extensions": {"code": "BAD_USER_INPUT"}
  }]
}

gRPC döndürür:

code: INVALID_ARGUMENT
message: "Name must be at least 2 characters"

Aynı doğrulama, protokole özel hata formatları.

Apidog ile Çok Protokollü API'ları Test Etme

Apidog, her üç protokolü de test etmeyi destekler.

REST Uç Noktasını Test Etme

POST https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt
Content-Type: application/json

{
  "userId": "user-123"
}

GraphQL Mutasyonunu Test Etme

mutation {
  adoptPet(
    petId: "019b4132-70aa-764f-b315-e2803d882a24"
    userId: "user-123"
  ) {
    id
    total
  }
}

gRPC Hizmetini Test Etme

grpc.petstore.v1.PetService/AdoptPet
{
  "pet_id": "019b4132-70aa-764f-b315-e2803d882a24",
  "user_id": "user-123"
}

Tutarlılığı Doğrulama

Her üç protokolün de aynı veriyi döndürdüğünü test edin:

REST uç noktasını çağırın
GraphQL mutasyonunu çağırın
gRPC hizmetini çağırın
Sonuçları karşılaştırın

Apidog bu protokoller arası testi otomatikleştirebilir.

Dağıtım Stratejileri

Strateji 1: Tek Hizmet

Tüm protokolleri tek bir hizmette dağıtın:

┌─────────────────────────┐
│  PetstoreAPI Service    │
│  ├── REST (port 8080)   │
│  ├── GraphQL (port 8081)│
│  └── gRPC (port 50051)  │
└─────────────────────────┘

Artıları: Basit dağıtım, paylaşılan kaynaklar Eksileri: Tüm protokoller birlikte ölçeklenir

Strateji 2: Ayrı Hizmetler

Her protokolü ayrı ayrı dağıtın:

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ REST Service │  │ GraphQL Svc  │  │ gRPC Service │
│ (port 8080)  │  │ (port 8081)  │  │ (port 50051) │
└──────────────┘  └──────────────┘  └──────────────┘
       │                 │                  │
       └─────────────────┴──────────────────┘
                         │
                  ┌──────────────┐
                  │ Shared Core  │
                  │   Library    │
                  └──────────────┘

Artıları: Bağımsız ölçekleme, protokol izolasyonu Eksileri: Daha karmaşık dağıtım

Strateji 3: API Ağ Geçidi

Protokole özel arka uçlara yönlendirmek için bir API ağ geçidi kullanın:

                ┌─────────────┐
                │ API Gateway │
                └─────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼──────┐ ┌────▼─────┐ ┌──────▼──────┐
│ REST Backend │ │ GraphQL  │ │ gRPC Backend│
└──────────────┘ └──────────┘ └─────────────┘

Artıları: Merkezi yönlendirme, hız sınırlama, kimlik doğrulama Eksileri: Ek gecikme, ağ geçidi karmaşıklığı

Modern PetstoreAPI basitlik için Strateji 1'i kullanır.

Sonuç

Çok protokollü API'lar, iş mantığını tekrarlamadan istemcilere esneklik sağlar. Protokol katmanlarını etki alanı mantığından ayırarak, paylaşılan bir çekirdekten REST, GraphQL ve gRPC'yi destekleyebilirsiniz.

Modern PetstoreAPI bu mimariyi tutarlı veri modelleri, paylaşılan doğrulama ve protokole özel adaptörlerle sergiler. İstemciler basitlik için REST'i, esneklik için GraphQL'i veya performans için gRPC'yi kullansalar da, aynı iş kurallarına sahip aynı evcil hayvan dükkanına erişirler.

Protokoller arası tutarlılığı sağlamak için çok protokollü API'larınızı Apidog ile test edin. Çok protokollü mimariyi eylemde görmek için Modern PetstoreAPI'yi keşfedin.

düğme

Sıkça Sorulan Sorular

Her üç protokolü de desteklemem gerekiyor mu?

Hayır. Halka açık API'lar için REST ile başlayın. İstemciler esnek veri çekme ihtiyacı duyuyorsa GraphQL ekleyin. Dahili mikro hizmetler için gRPC ekleyin. Yalnızca net bir kullanım durumunuz olduğunda protokolleri ekleyin.

Protokolleri nasıl tutarlı tutarım?

İş mantığını bir etki alanı katmanında paylaşın. Protokol adaptörleri yalnızca formatları çevirmeli, iş kuralları içermemelidir. Aynı veriyi döndürdüklerini doğrulamak için tüm protokolleri test edin.

Protokolleri bağımsız olarak sürümleyebilir miyim?

Evet. REST v2'de iken GraphQL v1'de olabilir. Ancak bu karmaşıklık yaratır. Mümkün olduğunda protokolleri senkronize tutmaya çalışın.

Protokoller arasında kimlik doğrulamasını nasıl yönetirim?

Tüm protokollerde aynı kimlik doğrulamasını kullanın. REST başlıklarında Taşıyıcı jetonlar kullanır. GraphQL aynı jetonları kullanır. gRPC meta verileri kullanır. Etki alanı katmanı jetonları aynı şekilde doğrular.

WebSocket ve SSE hakkında ne düşünüyorsunuz?

WebSocket ve SSE, API protokolleri değil, taşıma protokolleridir. Gerçek zamanlı güncellemeler için REST/GraphQL/gRPC ile birlikte ekleyebilirsiniz. Modern PetstoreAPI her ikisini de içerir.

Çok protokollü API'ları nasıl belgelendiririm?

REST için OpenAPI'yi, GraphQL için GraphQL şemasını ve gRPC için .proto dosyalarını kullanın. Modern PetstoreAPI her üçünü de https://docs.petstoreapi.com/ adresinde sunar.

Farklı protokoller için farklı veritabanları kullanabilir miyim?

Evet, ancak bu tutarlılık sorunları yaratır. Tüm protokoller için aynı veri katmanını kullanmak daha iyidir. Protokol adaptörlerinin format farklılıklarını yönetmesine izin verin.

Çok protokollü API'ları nasıl test ederim?

Tüm protokolleri tek bir araçta test etmek için Apidog'u kullanın. Protokoller arası tutarlılığı doğrulayan test paketleri oluşturun. REST, GraphQL ve gRPC'nin aynı işlemler için aynı veriyi döndürdüğünü test edin.