Mikro hizmetler tasarlama: API tasarımıDesigning microservices: API design

İletileri veya API çağrısı ile hizmetler arasındaki tüm veri alışverişi olur çünkü iyi API tasarımı, mikro hizmetler mimarisinde, önemlidir.Good API design is important in a microservices architecture, because all data exchange between services happens either through messages or API calls. API'ler oluşturmaktan kaçınmak için etkin olmalıdır geveze g/ç.APIs must be efficient to avoid creating chatty I/O. Hizmetler bağımsız olarak çalışan takımlar tarafından tasarlandığından, API güncelleştirmelerini diğer hizmetleri bölme, iyi tanımlanmış semantiği ve sürüm oluşturma düzenleri, olması gerekir.Because services are designed by teams working independently, APIs must have well-defined semantics and versioning schemes, so that updates don't break other services.

Mikro hizmetlere yönelik API tasarımı

API iki tür arasında ayrım yapmak önemlidir:It's important to distinguish between two types of API:

  • Genel API'leri, istemci uygulamaları arayın.Public APIs that client applications call.
  • Hizmetler arası iletişim için kullanılan arka uç API'leri.Backend APIs that are used for interservice communication.

Bu iki kullanım durumu biraz farklı gereksinimleri vardır.These two use cases have somewhat different requirements. Genel API, istemci uygulamaları, genellikle tarayıcı uygulamaları veya yerel mobil uygulamalar ile uyumlu olmalıdır.A public API must be compatible with client applications, typically browser applications or native mobile applications. Çoğu zaman, bu genel API, HTTP üzerinden REST kullanacağı anlamına gelir.Most of the time, that means the public API will use REST over HTTP. İçin arka uç API'leri, ancak ağ performansı dikkate almak gerekir.For the backend APIs, however, you need to take network performance into account. Hizmetlerinizi ayrıntı düzeyi bağlı olarak, çok miktarda ağ trafiği hizmetin iletişim neden olabilir.Depending on the granularity of your services, interservice communication can result in a lot of network traffic. Hizmetleri hızlı g/ç hale gelebilir.Services can quickly become I/O bound. Bu nedenle, seri hale getirme hızını ve yükü boyutu gibi konuları daha önemli hale gelmiştir.For that reason, considerations such as serialization speed and payload size become more important. HTTP üzerinden REST kullanarak bazı popüler alternatifleri gRPC, Apache Avro ve Apache Thrift içerir.Some popular alternatives to using REST over HTTP include gRPC, Apache Avro, and Apache Thrift. Bu protokolleri, ikili serileştirme destekler ve HTTP genellikle daha verimlidir.These protocols support binary serialization and are generally more efficient than HTTP.

Dikkat edilmesi gerekenlerConsiderations

API uygulama nasıl seçerken dikkat etmeniz gereken bazı işlemler aşağıda verilmiştir.Here are some things to think about when choosing how to implement an API.

REST vs RPC.REST vs RPC. REST stilinde bir arabirim RPC stilinde bir arabirim kullanarak arasında dengelerin göz önünde bulundurun.Consider the tradeoffs between using a REST-style interface versus an RPC-style interface.

  • Doğal bir yol olabilir REST modelleri kaynak etki alanı modeliniz express.REST models resources, which can be a natural way express your domain model. Geliştirilebilirlik teşvik eden HTTP fiilleri üzerinde temel bir Tekdüzen arabirimi tanımlar.It defines a uniform interface based on HTTP verbs, which encourages evolvability. Bu Etkisizliği, yan etkileri ve yanıt kodları açısından iyi tanımlanmış semantiğe sahip.It has well-defined semantics in terms of idempotency, side effects, and response codes. Ve ölçeklenebilirliği iyileştirdi durum bilgisi olmayan iletişimi uygular.And it enforces stateless communication, which improves scalability.

  • RPC işlemleri veya komutları daha odaklı.RPC is more oriented around operations or commands. Yerel yöntem çağrıları gibi RPC arabirimlerinin görünür olduğundan, sık iletişim kuran API'leri tasarlamak için neden olabilir.Because RPC interfaces look like local method calls, it may lead you to design overly chatty APIs. Ancak, bu RPC geveze anlamına gelmez.However, that doesn't mean RPC must be chatty. Yalnızca arabirim tasarlarken dikkatli kullanmanız gereken anlamına gelir.It just means you need to use care when designing the interface.

Bir RESTful arabirimi için en yaygın REST JSON'ı kullanarak HTTP üzerinden seçimdir.For a RESTful interface, the most common choice is REST over HTTP using JSON. RPC stilinde bir arabirim için gRPC, Apache Avro ve Apache Thrift gibi çeşitli popüler çerçeveleri vardır.For an RPC-style interface, there are several popular frameworks, including gRPC, Apache Avro, and Apache Thrift.

Verimliliği.Efficiency. Hız, bellek ve yükü boyutu açısından verimlilik kullanmayı düşünün.Consider efficiency in terms of speed, memory, and payload size. Genellikle gRPC tabanlı bir arabirim HTTP üzerinden REST hızlıdır.Typically a gRPC-based interface is faster than REST over HTTP.

Arabirim tanımı dili (IDL).Interface definition language (IDL). Bir IDL parametreleri olan yöntemleri tanımlamak ve bir API değerlerini döndürmek için kullanılır.An IDL is used to define the methods, parameters, and return values of an API. Bir IDL, istemci kodu ve Serileştirme kodu API belgeleri oluşturmak için kullanılabilir.An IDL can be used to generate client code, serialization code, and API documentation. IDLs test araçları Postman gibi API'si tarafından da kullanılır.IDLs can also be consumed by API testing tools such as Postman. GRPC ve Avro Thrift gibi çerçeveleri kendi IDL belirtimleri tanımlayın.Frameworks such as gRPC, Avro, and Thrift define their own IDL specifications. HTTP üzerinden REST standart IDL biçime sahip değildir, ancak bir Openapı yaygın seçenektir (önceki adıyla Swagger).REST over HTTP does not have a standard IDL format, but a common choice is OpenAPI (formerly Swagger). Bir HTTP REST API'leri biçimsel tanım dili kullanmadan da oluşturabilirsiniz, ancak ardından kod oluşturma ve sınama avantajlarını kaybedersiniz.You can also create an HTTP REST API without using a formal definition language, but then you lose the benefits of code generation and testing.

Serileştirme.Serialization. Nesneleri kablo üzerinden nasıl serileştirilen?How are objects serialized over the wire? Seçenekler, metin tabanlı biçimler (öncelikle JSON) ve protokolü arabellek gibi İkili biçimler içerir.Options include text-based formats (primarily JSON) and binary formats such as protocol buffer. İkili biçimler genellikle metin tabanlı biçimler hızlıdır.Binary formats are generally faster than text-based formats. Ancak, çoğu dil ve çerçeve JSON serileştirme desteklediğinden JSON birlikte çalışabilirlik, açısından avantajları vardır.However, JSON has advantages in terms of interoperability, because most languages and frameworks support JSON serialization. Bazı serileştirme biçimleri sabit bir şema gerektirir ve bazı bir şema tanımı dosyası derleme gerektirir.Some serialization formats require a fixed schema, and some require compiling a schema definition file. Bu durumda, bu adımı yapı işleminize dahil etmek gerekir.In that case, you'll need to incorporate this step into your build process.

Çerçeve ve dilden Destek.Framework and language support. HTTP, neredeyse tüm çerçeve ve dilden içinde desteklenir.HTTP is supported in nearly every framework and language. gRPC, Avro ve Thrift kitaplıkları, C++, C#, Java ve Python için vardır.gRPC, Avro, and Thrift all have libraries for C++, C#, Java, and Python. Thrift ve gRPC Git da destekler.Thrift and gRPC also support Go.

Uyumluluk ve birlikte çalışabilirlik.Compatibility and interoperability. GRPC gibi bir protokol seçin, bir protokol çevirisi katmanı Genel API ve arka uç arasındaki gerekebilir.If you choose a protocol like gRPC, you may need a protocol translation layer between the public API and the back end. A ağ geçidi bu işlevi gerçekleştirebilir.A gateway can perform that function. Ağ hizmeti kullanıyorsanız, hangi protokollerin hizmet ağı ile uyumlu olan göz önünde bulundurun.If you are using a service mesh, consider which protocols are compatible with the service mesh. Örneğin, linkerd HTTP ve Thrift gRPC için yerleşik destek sunmaktadır.For example, linkerd has built-in support for HTTP, Thrift, and gRPC.

Taban çizgisi önerimizde ikili Protokolü performans avantajlarını gerekmedikçe HTTP üzerinden REST seçmektir.Our baseline recommendation is to choose REST over HTTP unless you need the performance benefits of a binary protocol. HTTP üzerinden REST herhangi bir özel kitaplığı gerektirir.REST over HTTP requires no special libraries. Çağıranlar hizmetiyle iletişim kurmak için bir istemci saplama gerekmez çünkü en az eşlenmesiyle, oluşturur.It creates minimal coupling, because callers don't need a client stub to communicate with the service. Şema tanımları, test ve RESTful HTTP uç noktaları izleme desteklemek için Araçlar'ın zengin ekosistemlerini yoktur.There is rich ecosystems of tools to support schema definitions, testing, and monitoring of RESTful HTTP endpoints. Son olarak, bir protokol çevirisi katmanına arka uç ile istemci arasında zorunda kalmazsınız HTTP tarayıcı istemcileri ile uyumludur.Finally, HTTP is compatible with browser clients, so you don't need a protocol translation layer between the client and the backend.

Ancak, HTTP üzerinden REST seçerseniz, performans yapın ve yük testi senaryonuz için yeterince iyi gerçekleştiğini doğrulamak için erken geliştirme sürecinde, gerekir.However, if you choose REST over HTTP, you should do performance and load testing early in the development process, to validate whether it performs well enough for your scenario.

RESTful API tasarımıRESTful API design

RESTful API'leri oluşturmaya yönelik birçok kaynak vardır.There are many resources for designing RESTful APIs. Yararlı bulabileceğiniz bazı şunlardır:Here are some that you might find helpful:

Akılda tutulması gereken belirli bazı önemli noktalar aşağıda verilmiştir.Here are some specific considerations to keep in mind.

  • İç uygulama ayrıntıları sızıntı veya yalnızca bir iç veritabanı şeması yansıtan API'ler için dikkat edin.Watch out for APIs that leak internal implementation details or simply mirror an internal database schema. API, etki alanının modelini oluşturması gerekir.The API should model the domain. Hizmetler arasında bir sözleşme ve yeni işlevleri eklendiğinde çünkü yalnızca bazı kodları yeniden düzenlenen veya bir veritabanı tablosu normalleştirilmiş ideal olarak yalnızca değiştirmelisiniz.It's a contract between services, and ideally should only change when new functionality is added, not just because you refactored some code or normalized a database table.

  • İstemcisi, mobil uygulama ve masaüstü web tarayıcısı gibi farklı türlerde farklı yük boyutları veya etkileşim desenleri gerektirebilir.Different types of client, such as mobile application and desktop web browser, may require different payload sizes or interaction patterns. Kullanmayı uçlar için arka uçlar düzeni o istemci için en iyi bir arabirimi kullanıma sunan her istemci için ayrı arka uçları oluşturma.Consider using the Backends for Frontends pattern to create separate backends for each client, that expose an optimal interface for that client.

  • Yan etkileri olan işlemler için bunları etkili hale getirir ve PUT yöntemleri olarak uygularken göz önünde bulundurun.For operations with side effects, consider making them idempotent and implementing them as PUT methods. Güvenli yeniden denemeleri etkinleştirir ve dayanıklılığı artırabilir.That will enable safe retries and can improve resiliency. Bölümler alma ve iş akışı ve hizmetler arası iletişim bu sorunu daha ayrıntılı açıklanmaktadır.The chapters Ingestion and workflow and Interservice communication discuss this issue in more detail.

  • HTTP yöntemleri, burada bir yanıt yöntem hemen döner, ancak hizmet işlemi zaman uyumsuz olarak yürüten zaman uyumsuz semantiklere sahip olabilir.HTTP methods can have asynchronous semantics, where the method returns a response immediately, but the service carries out the operation asynchronously. Bu durumda, yöntem döndürmelidir bir HTTP 202 yanıt kodu, istek gösterir, işleme için kabul edildi, ancak işleme henüz tamamlanmadı.In that case, the method should return an HTTP 202 response code, which indicates the request was accepted for processing, but the processing is not yet completed.

REST DDD desenlerini eşlemeMapping REST to DDD patterns

Varlık ve toplam değer nesnesi gibi desenler, etki alanı modelinizdeki nesneler üzerinde belirli kısıtlamaları yerleştirmek için tasarlanmıştır.Patterns such as entity, aggregate, and value object are designed to place certain constraints on the objects in your domain model. DDD birçok tartışmalara desenleri (Paylaşımlarınızda) dil kavramları oluşturucular veya özellik alıcılar ve ayarlayıcılar gibi nesne yönelimli kullanarak modellenir.In many discussions of DDD, the patterns are modeled using object-oriented (OO) language concepts like constructors or property getters and setters. Örneğin, değer nesneleri sabit olması gerekiyor.For example, value objects are supposed to be immutable. Bir Paylaşımlarınızda programlama dilinde, bu değerler oluşturucuda atama ve özellikleri salt okunur yapma zorlamak:In an OO programming language, you would enforce this by assigning the values in the constructor and making the properties read-only:

export class Location {
    readonly latitude: number;
    readonly longitude: number;

    constructor(latitude: number, longitude: number) {
        if (latitude < -90 || latitude > 90) {
            throw new RangeError('latitude must be between -90 and 90');
        }
        if (longitude < -180 || longitude > 180) {
            throw new RangeError('longitude must be between -180 and 180');
        }
        this.latitude = latitude;
        this.longitude = longitude;
    }
}

Uyararak kodlama uygulamaları, geleneksel tek parça bir uygulamayı oluştururken özellikle önemlidir.These sorts of coding practices are particularly important when building a traditional monolithic application. Bir kod tabanı büyükse, çok sayıda alt sistemlerin kullanabilir Location nesne doğru davranışı zorlamak nesne için önemlidir.With a large code base, many subsystems might use the Location object, so it's important for the object to enforce correct behavior.

Başka bir örnek uygulamanın diğer bölümlerini doğrudan okuma ve yazma veri depolamak yapmayın sağlar depo modelidir:Another example is the Repository pattern, which ensures that other parts of the application do not make direct reads or writes to the data store:

! Bir insansız hava aracı ile depo diyagramı!Diagram of a Drone Repository

Mikro hizmetler mimarisinde, ancak Hizmetleri aynı kod tabanını paylaşan yok ve veri depoları paylaşmayın.In a microservices architecture, however, services don't share the same code base and don't share data stores. Bunun yerine, API'leri aracılığıyla iletişim kurarlar.Instead, they communicate through APIs. Burada Zamanlayıcı hizmeti insansız hava aracı ile hizmetten bir insansız hava aracı hakkında daha fazla bilgi ister bir durum düşünün.Consider the case where the Scheduler service requests information about a drone from the Drone service. İnsansız hava aracı ile hizmet kendi iç koduyla ifade bir insansız hava modelini içerir.The Drone service has its internal model of a drone, expressed through code. Ancak, Zamanlayıcı görmez.But the Scheduler doesn't see that. Bunun yerine geri alır bir gösterimi insansız hava aracı ile varlık — belki de bir JSON nesnesinde bir HTTP yanıtı.Instead, it gets back a representation of the drone entity — perhaps a JSON object in an HTTP response.

İnsansız hava aracı ile hizmet diyagramı

Zamanlayıcı hizmetine insansız hava aracı hizmetin iç modellerinin değiştiremez, veya insansız hava aracı ile hizmet veri deposuna yazma.The Scheduler service can't modify the Drone service's internal models, or write to the Drone service's data store. Bu, geleneksel monoliti kod ile karşılaştırıldığında bir küçük sunulan yüzey alanını insansız hava aracı ile hizmet uygulayan kod sahip olduğu anlamına gelir.That means the code that implements the Drone service has a smaller exposed surface area, compared with code in a traditional monolith. İnsansız hava aracı ile hizmet konumu sınıfı tanımlar, bu sınıfın kapsamı sınırlıdır — başka bir hizmet sınıfı doğrudan kullanacaktır.If the Drone service defines a Location class, the scope of that class is limited — no other service will directly consume the class.

Bu nedenlerle, bu kılavuz çok taktiksel DDD desenlerini teklifiyle olarak kodlama uygulamaları üzerinde odaklanın değil.For these reasons, this guidance doesn't focus much on coding practices as they relate to the tactical DDD patterns. Ancak, aynı zamanda REST API'ler aracılığıyla DDD deseni birçoğu modelleyebilir, ettik.But it turns out that you can also model many of the DDD patterns through REST APIs.

Örneğin:For example:

  • Toplamlar eşlemek için doğal olarak kaynakları kalan.Aggregates map naturally to resources in REST. Örneğin, teslim toplama bir kaynak olarak teslim API'sı tarafından açık.For example, the Delivery aggregate would be exposed as a resource by the Delivery API.

  • Toplamlar tutarlılık sınırlarıdır.Aggregates are consistency boundaries. Toplamlar işlemleri toplama tutarsız bir durumda hiçbir zaman bırakmanız gerekir.Operations on aggregates should never leave an aggregate in an inconsistent state. Bu nedenle, bir toplama iç durumunu işlemek bir istemci sağlayan API'ler oluşturmaktan kaçınmalısınız.Therefore, you should avoid creating APIs that allow a client to manipulate the internal state of an aggregate. Bunun yerine, toplamalar kaynakları olarak kullanıma sunma parçalı API'leri favor.Instead, favor coarse-grained APIs that expose aggregates as resources.

  • Varlıklar benzersiz kimliklerini içerir.Entities have unique identities. KALAN, URL biçiminde benzersiz tanımlayıcıları kaynaklara sahibiz.In REST, resources have unique identifiers in the form of URLs. Bir varlığın etki alanı kimliğine karşılık gelen kaynak URL'leri oluşturun.Create resource URLs that correspond to an entity's domain identity. Etki alanı kimlik eşleme URL'den istemciye donuk olabilir.The mapping from URL to domain identity may be opaque to client.

  • Alt varlıklar bir toplamanın kök varlıktan giderek erişilebilir.Child entities of an aggregate can be reached by navigating from the root entity. İzlerseniz HATEOAS ilkesinden alt varlıklar ulaşılabilir üst varlık gösterimini bağlantıları aracılığıyla.If you follow HATEOAS principles, child entities can be reached via links in the representation of the parent entity.

  • Değişmez değer nesneler olduğundan, güncelleştirmeleri tüm değer nesnesi değiştirilerek gerçekleştirilir.Because value objects are immutable, updates are performed by replacing the entire value object. KALAN, PUT veya PATCH istekleri aracılığıyla güncelleştirmeleri uygulayın.In REST, implement updates through PUT or PATCH requests.

  • Bir depo ekleyebilir veya nesneleri temel alınan veri deposu ayrıntılarını özetleyen bir koleksiyondaki istemciler sorgu olanak tanır.A repository lets clients query, add, or remove objects in a collection, abstracting the details of the underlying data store. KALAN, bir toplama yöntemleri koleksiyonu sorgulama veya yeni varlıklar koleksiyona eklemek için farklı bir kaynak olabilir.In REST, a collection can be a distinct resource, with methods for querying the collection or adding new entities to the collection.

Apı'lerinizi tasarlarken, bunların yalnızca veri modeli, ancak ayrıca iş işlemleri ve veri kısıtlamalar içinde etki alanı modeli nasıl express hakkında düşünün.When you design your APIs, think about how they express the domain model, not just the data inside the model, but also the business operations and the constraints on the data.

DDD kavramıDDD concept REST eşdeğeriREST equivalent ÖrnekExample
Toplam DeğerAggregate KaynakResource { "1":1234, "status":"pending"... }
KimlikIdentity URL'siURL https://delivery-service/deliveries/1
Alt varlıklarChild entities BağlantılarLinks { "href": "/deliveries/1/confirmation" }
Değer nesnelerini güncelleştirmeUpdate value objects PUT veya PATCHPUT or PATCH PUT https://delivery-service/deliveries/1/dropoff
DepoRepository KoleksiyonCollection https://delivery-service/deliveries?status=pending

API sürümü oluşturmaAPI versioning

Bir API, hizmet ve istemcileri veya hizmet tüketicileri arasında bir sözleşmedir.An API is a contract between a service and clients or consumers of that service. Bir API değişirse, API, bağlı istemciler bozucu riski yoktur dış istemciler veya diğer mikro hizmetler olanlardır.If an API changes, there is a risk of breaking clients that depend on the API, whether those are external clients or other microservices. Bu nedenle, yaptığınız API değişiklikleri sayısını en aza indirmek için bir fikirdir.Therefore, it's a good idea to minimize the number of API changes that you make. Genellikle, temel alınan uygulamada değişiklikleri API'SİNDE herhangi bir değişiklik gerektirmez.Often, changes in the underlying implementation don't require any changes to the API. Gerçekçi olarak, ancak belirli bir noktada, yeni özellikler veya mevcut bir API'yi değiştirme gerektiren yeni özellikler eklemek isteyebilirsiniz.Realistically, however, at some point you will want to add new features or new capabilities that require changing an existing API.

Her mümkün yapma API geriye dönük olarak uyumlu değiştirir.Whenever possible, make API changes backward compatible. Örneğin, alanın var olmasını beklediğiniz istemciler bozabileceğinden bir alanın bir modelden kaldırılması kaçının.For example, avoid removing a field from a model, because that can break clients that expect the field to be there. İstemciler, bir yanıt olarak anlamadığınız herhangi bir alan yok saymanız gerekir çünkü bir alan ekleme, uyumluluk, kesmez.Adding a field does not break compatibility, because clients should ignore any fields they don't understand in a response. Ancak, hizmet nerede eski bir istemciyi yeni bir istek alanında atlar durum işlemesi gerekir.However, the service must handle the case where an older client omits the new field in a request.

Sürüm oluşturma API'si sözleşmeniz destekler.Support versioning in your API contract. Bir API değişiklik belirtiyorsa, yeni bir API sürümü tanıtır.If you introduce a breaking API change, introduce a new API version. Önceki sürüm desteği ve çağırmak için hangi sürümün seçin, istemcilerin izin devam edin.Continue to support the previous version, and let clients select which version to call. Çeşitli şekillerde bunun için vardır.There are a couple of ways to do this. Yalnızca aynı hizmetin her iki sürümlerinde kullanıma sunmak için biridir.One is simply to expose both versions in the same service. Başka bir hizmet yan yana iki sürümünü çalıştırın ve bir ya da HTTP yönlendirme kurallarına göre diğer sürüm, istekleri yönlendirmek için bir seçenektir.Another option is to run two versions of the service side-by-side, and route requests to one or the other version, based on HTTP routing rules.

Sürüm oluşturma

Geliştirici zaman, sınama ve işletimsel ek yük açısından birden çok sürümü destekleyen bir maliyeti yoktur.There's a cost to supporting multiple versions, in terms of developer time, testing, and operational overhead. Bu nedenle, mümkün olan en kısa sürede eski sürümler kullanım dışı bırakılsın iyi olur.Therefore, it's good to deprecate old versions as quickly as possible. İç API'ler için yeni sürüme geçirme yardımcı olmak için diğer ekiplerle olan API takımın çalışabilir.For internal APIs, the team that owns the API can work with other teams to help them migrate to the new version. Bu durum, takımlar arası idare sürecine sahip yararlıdır andır.This is when having a cross-team governance process is useful. API'yi yerel istemci uygulamaları veya üçüncü taraflar tarafından özellikle kullanılan dış (ortak) API'leri için bunu bir API sürümü kullanımdan kaldırmaya daha zor olabilir.For external (public) APIs, it can be harder to deprecate an API version, especially if the API is consumed by third parties or by native client applications.

Bir hizmet uygulaması değiştirildiğinde bir sürüm değişikliği etiketlemek kullanışlıdır.When a service implementation changes, it's useful to tag the change with a version. Sürüm hatalarında sorun giderme sırasında önemli bilgileri sağlar.The version provides important information when troubleshooting errors. Tam olarak hangi sürümünün bir hizmet olarak adlandırılıyordu bilmek, kök neden analizi için çok yararlı olabilir.It can be very helpful for root cause analysis to know exactly which version of the service was called. Kullanmayı semantic versioning hizmet sürümlerindeki.Consider using semantic versioning for service versions. Semantic versioning kullanan bir önemli. KÜÇÜK. Düzeltme Eki biçimi.Semantic versioning uses a MAJOR.MINOR.PATCH format. Varsa önemli ancak, istemciler yalnızca API ana sürüm numarası veya büyük olasılıkla alt sürümü seçmeniz gerekir (ancak) değişiklikleri ikincil sürümleri arasında.However, clients should only select an API by the major version number, or possibly the minor version if there are significant (but non-breaking) changes between minor versions. Diğer bir deyişle, istemciler için sürüm 1 arasında bir API 2 sürümünü seçmek için ancak sürüm 2.1.3 seçmek şüphelenilebilir.In other words, it's reasonable for clients to select between version 1 and version 2 of an API, but not to select version 2.1.3. Ayrıntı düzeyi izin verirseniz, bir yaygınlaşmasının sürümleri desteklemek bağlantıyla karşılaşabilirsiniz.If you allow that level of granularity, you risk having to support a proliferation of versions.

Daha ayrıntılı bir açıklaması API sürümü oluşturma için RESTful web API'si sürümü oluşturma.For further discussion of API versioning, see Versioning a RESTful web API.