Phiên bản API dịch vụ web

Question

Tôi cung cấp API dịch vụ web nhỏ cho khách hàng mà tôi dự định phát triển theo thời gian. Vì vậy, tôi cần một số loại phiên bản, nhưng tôi không thể tìm thấy bất kỳ thông tin về cách bạn làm một cái gì đó như thế.

Có phương pháp hay nhất không?

Làm cách nào để tiếp tục thêm chức năng mới mà không vi phạm tính tương thích với người tiêu dùng dịch vụ web?

Answer 1

Thêm "số phiên bản API" làm thông số trong tất cả các API của bạn, sau đó triển khai mẫu chiến lược trong mã dịch vụ web của bạn nơi số phiên bản ra lệnh sử dụng chiến lược nào.

Answer 2

Tôi thường thêm chuỗi phiên bản vào URL dịch vụ web, cung cấp cho tôi "điểm cuối được phiên bản". Mã thực hiện các điểm cuối đó có thể được chia sẻ, nếu sự khác biệt là tầm thường và có thể được xử lý bởi cùng một mã, hoặc mã có thể được nhân bản, hoặc một nơi nào đó ở giữa.

Các điểm cuối được phiên bản khác nhau cũng có thể sử dụng Lược đồ XML được phiên bản, nếu đó là những gì bạn cần.

Answer 3

Phiên bản là một chủ đề phức tạp, vì vậy trước tiên, bạn cần xác định mục tiêu của mình theo cách mô tả hơn. Nó sẽ là tuyệt vời để nói rằng bạn có một giao diện đảm bảo bạn sẽ không bao giờ phá vỡ khả năng tương thích, nhưng tùy thuộc vào những gì các chức năng mới là, mà thậm chí có thể không thể. Vì vậy, có những tình huống khác nhau và sự cân bằng khác nhau.

Nếu mục đích của bạn là chỉ cung cấp chức năng mới cho người tiêu dùng mới và tất cả người tiêu dùng của bạn là người tiêu dùng trực tiếp (không trung gian, khuôn khổ, v.v.) thì cách tiếp cận riêng biệt là lựa chọn tốt nhất. Mỗi lần bạn thêm đối tượng địa lý có nguy cơ bị hỏng, hãy tạo điểm cuối mới, cung cấp cho nó một số phiên bản mới và sau đó cho người tiêu dùng biết để xác thực và thay đổi cấu hình của họ. Chiến lược này là khá cố gắng và đúng sự thật, nhưng nó có những hạn chế của việc đưa gánh nặng lên người tiêu dùng để giữ cho đến nay. Ngoài ra, nếu có sự phụ thuộc giữa các dịch vụ, nó có thể trở thành việc vặt để theo dõi. Mặt khác là nếu mã phá vỡ nó không phải (trực tiếp) lỗi của bạn.

Chiến lược chính khác là giao diện mở rộng. Có ba loại khác nhau ở đây mà tôi biết. Đầu tiên, là loại giao diện cố gắng mô tả tốt tên miền dịch vụ mà mọi tính năng có thể bạn có thể thêm bằng cách nào đó có thể được cung cấp cho giao diện hiện có. Nếu đó là âm thanh khó khăn, nó được. Bạn có thể gọi đây là giao diện hoàn hảo. Mọi thứ đều được mô tả đầy đủ, nhưng toàn bộ miền cũng được mô tả hoàn toàn. Các "hoàn hảo" thực sự chỉ trên giấy mặc dù.

Loại thứ hai là loại trông giống như giao diện bình thường nhưng thêm các điểm mở rộng chung. Trong WSDLs, điều này có nghĩa là xs: any, các cặp giá trị tên hoặc tương tự. Bạn có thể gọi đây là giao diện mở rộng cơ bản. Nó không quá khó để làm, nhưng nó không phải không có biến chứng của nó. Các điểm mở rộng có thể làm cho giao diện trở nên khó khăn hơn trong công cụ nhất định (xs: any), hoặc mất một số khả năng xác nhận đầu vào và đầu ra của bạn (cặp tên-giá trị). Nó cũng khá dễ dàng để lạm dụng những điểm mở rộng trong một cách mà làm cho phiên bản 3 hoặc 4 khá khó sử dụng.

Loại thứ ba là loại chuyển đổi giao diện của bạn thành luồng byte. Bạn có thể gọi những giao diện thần thánh này. Họ không phải là không có lý do của họ, nhưng nếu bạn đang sử dụng một, bạn có thể muốn hỏi tại sao bạn đang sử dụng dịch vụ web ở tất cả. Có lẽ bạn nên suy nghĩ về TCP/IP thô hoặc HTTP GET/POST cơ bản. Nhưng có thể bạn đang chán ngấy với sự phức tạp của WSDL và XSD và bạn chỉ muốn bắt đầu từ đầu nhưng bạn bị ràng buộc với các dịch vụ web vì một lý do cơ sở hạ tầng nào đó. Tuy nhiên, hãy nhận ra rằng khi bạn bắt đầu con đường này, bạn sẽ cần một cách hoàn toàn mới để mô tả cho người tiêu dùng biết cách sử dụng dịch vụ của bạn, và nếu bạn sử dụng XSD cho điều đó ... bạn đã bắt đầu.

Đặt cược tốt nhất của bạn là biết tất cả các tùy chọn này và tiếp cận thiết kế dịch vụ của bạn bằng cách đầu tiên thử "giao diện hoàn hảo", sau đó từ bỏ và thêm các điểm mở rộng chung. Việc cố gắng thiết kế giao diện hoàn hảo sẽ buộc bạn phải học những thứ sẽ làm cho dịch vụ của bạn tốt hơn, không chỉ giao diện của bạn, nhưng nó sẽ mất thời gian, và nếu bạn không giới hạn thời gian đó, sẽ mất mãi mãi.

Một chút ngắn của giao diện thần thực sự, có giao diện trình bao bọc. Nếu hệ thống của bạn có các lớp, bạn cũng muốn giao diện của mình nằm trong các lớp. Khi bạn thay đổi lớp B, bạn chỉ muốn thay đổi lớp B, không phải tất cả các cá thể trong lớp C.

Answer 4

Một trong những khả năng là thiết kế tất cả các hoạt động dịch vụ web chỉ có một tham số của một kiểu kế thừa từ một số trừu tượng loại chứa số phiên bản. Cách tiếp cận này được thực hiện bởi eBay web services platform. Something như sau:

<xsd:complexType name="AbstractRequestType"> 
    <xsd:attribute name="version" type="string" /> 
    .... 

<xsd:complexType name="AddCustomerRequestType"> 
    <xsd:complexContent> 
    <xsd:extension base="AbstractRequestType"> 
    .... 

then use AddCustomerRequestType as a type of only parameter 
in addCustomer web service operation. 

Ngoài ra nếu bạn làm việc trên http bạn có thể yêu cầu thêm phiên bản như một http GET tham số url endpoint dịch vụ web, vì vậy bạn sẽ có thể phát hiện phiên bản yêu cầu một cách dễ dàng http://server/service?version=1

Answer 5

chiến lược phổ biến nhất mà tôi đã nhìn thấy là phiên bản WSDL bằng cách thêm xác định versioning (thường yyyy/MM[/dd]) để không gian tên của các đối tượng trong wsdl, tức là:

targetNamespace="http://schemas.mycompany.com/2010/01/widgets" 

Điều này có thể được thực hiện ở mức a- type (types/schema) hoặc ở toàn bộ cấp WSDL - <definitions> trong 1,1 hoặc <description> trong 2.0.

Hơi ngày, nhưng this link từ IBM phát triển công trình cung cấp cơ sở lý luận cho cách tiếp cận này, và đặc biệt là khi các phiên bản cần phải được tăng lên:

ngược phiên bản tương thích/thay đổi non-breaking:

• Thêm hoạt động mới
• Thêm loại mới

thay đổi Breaking:

• Loại bỏ hoặc đổi tên hoạt động
• Thay đổi các thông số đến một phương pháp
• Thay đổi một loại phức tạp