Khi tạo một api tôi có nên gắn bó với các chức năng nhỏ và nhiều cuộc gọi, hoặc một vài cuộc gọi và chức năng lớn?

Tôi có một nền tảng đường ray mà tôi duy trì. Nó có rất nhiều ứng dụng web khác nhau được xây dựng trên nó. Tuy nhiên, hiện tại một khách hàng đang yêu cầu API để họ có thể giữ người dùng trên trang web của họ, nhưng tận dụng một số tác vụ tự động mà chúng tôi có.

Nền tảng được sử dụng để xây dựng các ứng dụng bảo hiểm và cho phép họ mua hàng trực tuyến, cũng như cung cấp các cách để tải xuống tài liệu liên quan đến chính sách của bạn.

Vì vậy, câu hỏi của tôi khi xây dựng API là đây:

Khi tôi phải làm rất nhiều thứ, giống như validate, tạo user, user profilevà policy, khá nhiều cùng một lúc. Tôi có nên thực hiện 4 cuộc gọi API riêng biệt và khiến khách hàng xây dựng 4 cuộc gọi về phía họ. HOẶC tôi nên có một cuộc gọi chấp nhận nhiều tham số, xác thực ứng dụng khách và tạo cả 3 điều đó cùng một lúc, đơn giản hóa mọi thứ cho máy khách?

Trong trường hợp này, ứng dụng khách nhận được tất cả các thông tin cần thiết, do đó, không giống như có một luồng tự nhiên trong ứng dụng của họ khi nó tạm dừng và họ có thể thực hiện cuộc gọi API đến nền tảng của tôi.

Trước đây đã đứng về phía khách hàng sử dụng nhiều API, nhưng điều quan trọng của tôi là làm cho nó trở nên đơn giản cho khách hàng nhất có thể và khiến họ thực hiện chỉ một cuộc gọi. Tuy nhiên, điều này dẫn đến khá lớn functionstrong API, mà tôi cũng không phải là người hâm mộ.

Làm thế nào để bạn đề nghị tôi giải quyết điều này?

Lưu ý, tôi không tin tưởng lắm vào khả năng của khách hàng khi triển khai API phức tạp về phía họ.

Làm thế nào về cả hai? Có API " cấp thấp " (có thể nói) hiển thị các chức năng của hệ thống và có một "lớp" khác hiển thị các dịch vụ mà khách hàng có thể muốn thực hiện. Lớp này sẽ sử dụng các API cấp thấp cần thiết nhưng chúng vẫn được hiển thị nếu khách hàng muốn chúng.

CẬP NHẬT: Để bao gồm một số điểm tuyệt vời và ý kiến ​​được thực hiện bởi những người khác.

1. Xem xét nếu khách hàng sẽ cần phải gọi một trong các phương thức API nhỏ hơn, ví dụ: Có khả thi khi gọi createdUserProfile mà không cần gọi creatUser không? Nếu không thì đừng phơi bày phương pháp đó. Cảm ơn NoobsAreP People2

2. Một điểm đơn giản nhưng tuyệt vời. Điểm mấu chốt với việc tiết lộ một cái gì đó trong API - bạn không bao giờ có thể làm lộ nó. Đưa ra mức tối thiểu cần thiết để hoạt động và sau đó mở rộng thay vì phơi bày mọi thứ và ... tốt, sau đó việc trần trụi và thực hiện các thay đổi có thể gây bối rối và khó xử . Cảm ơn MichaelT

Tôi nghĩ rằng bạn đang nhìn nó sai cách. Đừng lo lắng về lớn | cuộc gọi nhỏ hoặc nhiều | vài cuộc gọi

Hãy suy nghĩ về các đối tượng kinh doanh và các hành động có thể được thực hiện với | cho | chống lại những đối tượng đó

Bạn đã có:

• Người dùng
• Chính sách
• Giá
• ...

Vì vậy, bạn nên tạo các lệnh gọi API xung quanh các đối tượng đó.

• Người dùng. Tạo
• Người dùng.UpdatePassword
• Chính sách
• ...

Ý tưởng là tạo ra các hoạt động nguyên tử hoặc gần nguyên tử dựa trên các đối tượng kinh doanh và hành động của họ. Điều này sẽ đơn giản hóa thiết kế và mã hóa - các cuộc gọi thực hiện những gì đối tượng kinh doanh nên làm phù hợp với mô hình tinh thần hoặc kỳ vọng của các lập trình viên. Khi các lập trình viên hoặc kiến ​​trúc sư đang thảo luận các yêu cầu với các nhà phân tích kinh doanh thì tất cả họ có thể sử dụng cùng một thuật ngữ và quy trình hoạt động chung.

Vấn đề với các cuộc gọi loại lớn hơn, tất cả trong một là nguy cơ tác dụng phụ. Nếu Policy.Create cũng sinh ra một Người dùng và kích hoạt một số hành động khác, thì điều đó sẽ phá vỡ sự mong đợi của các lập trình viên. Tương tự như vậy, rất nhiều cuộc gọi nhỏ buộc lập trình viên phải nhớ gọi A và sau đó là B và sau đó là C để thực hiện một hoạt động kinh doanh "đơn lẻ".

Và cách bạn đặt tên cho các cuộc gọi sẽ dựa trên những gì Rails và các dịch vụ web hỗ trợ của bạn sẽ hỗ trợ.

Để được kê đơn nhiều hơn, điều này sẽ tạo ra một số cuộc gọi có một số tham số và có thể có nhiều cuộc gọi ở mặt sau bị che khuất cho máy khách. Bạn cũng sẽ kết thúc với một số cuộc gọi khá nhanh / đơn giản trong đó API ít hơn một trình bao bọc cho thói quen cơ bản.

Tôi nghĩ rằng cảm giác ruột của bạn là đúng - làm cho API đơn giản cho người tiêu dùng. Ở một mức độ nào đó, đây là triết lý đằng sau Hợp đồng hướng đến người tiêu dùng .

Cụ thể hơn, API nên trưng ra các trường hợp sử dụng kinh doanh phù hợp. Hãy xem xét lĩnh vực kinh doanh trong tay - có thực sự cần những chức năng cấp thấp đó không? Hạn chế của việc đóng gói chúng là gì? Các hàm lớn trong API không phải là vấn đề trong chính chúng. Điều gì sẽ là một vấn đề là nếu một chức năng lớn sắp xếp các hoạt động có thể cần được phân vùng để cho phép sự can thiệp của người tiêu dùng.

Cá nhân, tôi thích các API:

1. được tối ưu hóa theo cách mà các trường hợp sử dụng thông thường có thể dễ dàng thực hiện
2. các cuộc gọi liên quan đến hoạt động CRUD được định hướng theo đợt hoặc có phiên bản theo đợt
3. cho phép phản ánh (để mọi người viết plugin hoặc liên kết cho các ngôn ngữ máy tính khác có thể tự động hóa quy trình)