2015-05-14 19 views
27

Tôi mới sử dụng Laravel (4 và 5) và gần đây tôi đang làm việc trên API RESTful. Để cho phép nhiều phiên bản của API, tôi đang sử dụng URL để xác định phiên bản.Thiết kế phiên bản API RESTavel RESTful

tôi đọc theo bài này và nó dường như hầu hết mọi người sau đây phương pháp này: How to organize different versioned REST API controllers in Laravel 4?

Folders cấu trúc:

/app 
    /controllers 
    /Api 
     /v1 
     /UserController.php 
     /v2 
     /UserController.php 

Và trong các tập tin UserController.php tôi đặt không gian tên cho phù hợp:

namespace Api\v1; 

hoặc

namespace Api\v2; 

và trong các tuyến đường:

Route::group(['prefix' => 'api/v1'], function() { 
    Route::get('user',  'Api\v1\[email protected]'); 
    Route::get('user/{id}', 'Api\v1\[email protected]'); 
}); 

Route::group(['prefix' => 'api/v2'], function() { 
    Route::get('user',  'Api\v2\[email protected]'); 
    Route::get('user/{id}', 'Api\v2\[email protected]'); 
}); 

URL sẽ được đơn giản http://..../api/v1 cho phiên bản 1 và http://..../api/v2 cho phiên bản. Điều này là thẳng về phía trước.

Câu hỏi của tôi là: Điều gì sẽ xảy ra nếu tôi xây dựng nâng cấp nhỏ api, hãy nói v1.1, tôi làm cách nào để tổ chức cấu trúc thư mục của mình? Suy nghĩ của tôi là điều này và nó vẫn còn tốt như dấu chấm là tên hợp lệ của các thư mục?

/app 
    /controllers 
    /Api 
     /v1 
     /UserController.php 
     /v1.1 
     /UserController.php 
     /v1.2 
     /UserController.php 
     /v2 
     /UserController.php 

Ngoài ra, Tôi nên viết không gian tên như thế nào? Đây không phải là không gian tên như thế này

namespace Api\v1.1; 

Có quy ước đặt tên nào tôi có thể tham khảo để sử dụng "dấu chấm" không?

Lưu ý: Tôi không muốn gọi nó là phiên bản v2 vì đây không phải là bản nâng cấp lớn.

Trả lời

29

IMO, các bản nâng cấp nhỏ không được xuất bản các thay đổi đột phá đối với API. Vì vậy, đề nghị của tôi là để dính vào các API số nguyên phiên bản. Các cải tiến không có vấn đề gì, nhưng các điểm cuối hiện tại sẽ hoạt động như bình thường.

Bằng cách này, các phiên bản API của bạn sẽ được đồng bộ hóa với tiền tố tuyến đường và không gian tên cũng như các thử nghiệm.

VÍ DỤ

  1. Bạn bắt đầu với v1.0
  2. Bạn làm cho một chút thay đổi (ví dụ. Git-tag v1.1) mà không mang lại những thay đổi phá vỡ để api của bạn. Có cần thiết cho các nhà phát triển để làm bất cứ điều gì khác trong mã của họ? Không có. Vì vậy, bạn có thể safeley để cho URI-Prefix ở lại V1, để các nhà phát triển gọi api của bạn không cần phải thay đổi tất cả mã của họ đang gọi API của bạn (và do đó, tự động được hưởng lợi từ phiên bản nhỏ mới). Có thể bạn vừa sửa lỗi, điều này làm cho mã của họ hoạt động như mong đợi hoặc bạn đã xuất bản một tính năng mới, mà bản thân nó không phá vỡ các cuộc gọi tính năng hiện có.
  3. Ứng dụng của bạn phát triển và bạn xuất bản phiên bản mới được thiết kế lại của API bạn có chứa các thay đổi đột phá. Trong trường hợp này, bạn xuất bản tiền tố API-URI mới (V2).

Hãy lưu ý rằng bạn có thể theo dõi các phiên bản nhỏ bên trong (ví dụ: trong SCM), nhưng không cần nhà phát triển thay đổi tất cả các cuộc gọi API của họ chỉ để hưởng lợi từ lỗi nhỏ đó được phát hành. Dù sao, nó là tốt đẹp của khóa học nếu bạn thông báo cho khách hàng của bạn về các phiên bản nhỏ mới hơn và sửa lỗi hoặc cải tiến mà họ cung cấp (blog, bản tin, ..)

Hãy để tôi thêm, rằng tôi không biết bất kỳ API RESTful với tiền tố API-URL nhỏ, vì vậy tôi đoán đây là một thực tế khá phổ biến.

+0

hi đầu phun, chế độ xem của bạn khác với aeryaguzov. bạn có nghĩa là nó phải là v2 thay vì v1.1, và không thực hiện bất kỳ thay đổi nào đối với các mã v1 hiện có? –

+0

Cảm ơn bạn đã phản hồi! Tôi đã chỉnh sửa câu trả lời. Tôi hy vọng tôi đã làm cho điểm của tôi rõ ràng hơn một chút. – nozzleman

+0

Tôi đang xem xét việc triển khai phiên bản API. Nếu sử dụng cấu trúc phiên bản này cho v1, v2, v.v ... sẽ có bất kỳ vấn đề nào khi nhà soạn nhạc được chạy và nó có tự động tải không? – JBMcClure

5

Bạn không thể sử dụng dấu chấm, thay vào đó hãy sử dụng dấu gạch dưới.

Nhưng ...

Một api được thiết kế tốt phải có BC giữa các phiên bản nhỏ, do đó bạn không cần phải tạo ra phiên bản mới cho bản cập nhật nhỏ, thay vào đó bạn cần phải viết mã tương thích.

+0

Hiểu điểm của bạn. Điều đó có nghĩa là tôi nên mở rộng hoặc thêm mã mới vào bộ điều khiển v1. –

Các vấn đề liên quan