Sofa - Cách tốt nhất để REST (là GraphQL)

Kết thúc cuộc tranh luận REST vs GraphQL một lần và mãi mãi

Kích hoạt API REST trong tích tắc

TL; DR

  • Don Tiết chọn giữa REST và GraphQL - tự động tạo API RESTful hoàn toàn từ triển khai GraphQL của bạn (với một thư viện và một dòng mã)
  • Nhận hầu hết các lợi ích của GraphQL trên phụ trợ và giao diện, trong khi sử dụng và hiển thị REST
  • Hỗ trợ tất cả các máy khách hiện tại của bạn với REST trong khi cải thiện ngăn xếp phụ trợ của bạn với GraphQL
  • Tạo các điểm cuối REST tùy chỉnh, hoàn toàn phù hợp với khách hàng cho giao diện của bạn chỉ bằng cách đặt tên tuyến và đính kèm truy vấn
  • Ngừng tranh luận về REST vs GraphQL. Sử dụng GraphQL, tạo REST và tận dụng tốt nhất từ ​​cả hai
  • Nói cách khác (REST to GraphQL), bạn đã giành được những thứ tốt nhất của cả hai thế giới nhưng kém mạnh mẽ hơn, khó duy trì việc triển khai máy chủ hơn với một số lợi ích của GraphQL. Đó là một khởi đầu tốt và nhanh chóng cho một di chuyển mặc dù ..

Đợi đã, CÁI GÌ!?

Nhiều bài viết đã được viết về những ưu và nhược điểm của API GraphQL và REST và cách quyết định sử dụng cái nào. Tôi sẽ không lặp lại những điều đó ở đây ..

Rất nhiều thời gian và công sức dành cho các chuyên gia tư vấn thông minh để viết những bài báo đó, đọc những bài báo đó, trong khi hầu hết chúng được hoàn thành với bản tin, nó phụ thuộc vào tóm tắt trường hợp sử dụng của bạn, mà không thực sự chỉ định các trường hợp sử dụng đó!

Tôi đã làm việc với các API REST, GraphQL và SOAP trong nhiều năm. Vì vậy, tôi nghĩ, tại sao không đưa ra một danh sách các trường hợp sử dụng đó và cho từng trường hợp cần kiểm tra - bạn không thể làm gì trong GraphQL mà bạn có thể làm với REST và bạn không muốn làm gì với GraphQL và bạn sẽ thích REST.

Sau khi tạo danh sách đó, tôi đột nhiên có một suy nghĩ - nếu có một tùy chọn khác - nếu máy chủ GraphQL mạnh mẽ của tôi có thể tạo API REST cho tôi thì sao?

Sau đó, tôi có thể có được tốt nhất của cả hai thế giới!

Càng đi sâu vào ý tưởng và triển khai, tôi càng nhận ra rằng không chỉ chúng tôi có thể tạo cả hai loại API cho chúng tôi, mà ngay cả khi chúng tôi chỉ muốn trưng ra API REST và không khách hàng nào của chúng tôi sử dụng GraphQL, GraphQL là cách tốt nhất để tạo API REST!

Làm thế nào để câu trên thậm chí có ý nghĩa?!

Thông thường khi chúng tôi (The Guild) giúp các công ty và tổ chức hiện đại hóa API của họ, người đầu tiên hiểu được lợi ích của GraphQL là các nhà phát triển frontend, vì những lý do rõ ràng. Nhưng ngay khi các nhà phát triển phụ trợ, Get Get it, họ trở thành những người ủng hộ công nghệ lớn nhất. Nhưng họ vẫn cần hỗ trợ khách hàng hiện tại và các đối tác bên thứ 3.

Đó là lý do tại sao các API REST được tạo mới này nhận được rất nhiều tính năng và lợi ích từ việc triển khai GraphQL nội bộ khiến các nhà phát triển phụ trợ hài lòng:

  • Tài liệu được tạo đầy đủ luôn cập nhật (Swagger, OpenAPI và GraphiQL)
  • API thực sự RESTful ra khỏi hộp
  • Đăng ký GraphQL dưới dạng Webhooks
  • Xác thực dữ liệu thời gian chạy - chắc chắn 100% rằng dữ liệu được tìm nạp khớp với cấu trúc lược đồ và truy vấn. Bạn gửi chính xác những gì tôi muốn gửi, chuỗi là một chuỗi, một đối tượng có chính xác các thuộc tính.
  • Tạo một điểm cuối tùy chỉnh bây giờ là vấn đề chọn tên tuyến và đính kèm truy vấn vào nó. làm xong. Không còn công việc thủ công trong việc tạo và duy trì các điểm cuối cụ thể của khách hàng!
  • Sử dụng triết lý GraphQL, về việc phát triển API thông qua các lược đồ - không di chuyển API V1 - V2 đau đớn hơn.
  • Sử dụng công nghệ hiện đại dễ thuê người hơn. Các công ty như Facebook, Airbnb và các công ty khác đã chuyển sang GraphQL. Không ai trong số họ đã quay trở lại.
  • Sức mạnh của trình phân giải GraphQL để tạo triển khai API của bạn, thay vì các trình điều khiển được viết thủ công từ MVC

Những gì tôi nhận được từ việc có người giải quyết?

  • Dễ dàng chuyển đổi dữ liệu để phù hợp với phản hồi (Lược đồ GraphQL). Điều đó bởi vì mọi thực thể đều có trình phân giải riêng, do đó ánh xạ được chuyển thành các phần nhỏ hơn và được sử dụng lại trên toàn bộ ứng dụng.
  • GraphQL cho phép bạn dễ dàng chia sẻ dữ liệu trên mọi trình phân giải, chúng tôi gọi đó là Ngữ cảnh.
  • Buộc bạn xác định và giải quyết dữ liệu theo cách có ý kiến ​​thực sự giúp xây dựng API. Nó chạy các hàm song song (các hàm được lồng cùng cấp), xử lý không đồng bộ và cuối cùng, nó có trách nhiệm hợp nhất tất cả các mục đó thành một đối tượng duy nhất, vì vậy bạn không phải nghĩ về nó.

Sofa - Sử dụng GraphQL để tạo API RESTful

Vì vậy, chúng tôi đã tạo ra Sofa (ý định chơi chữ), một thư viện mã nguồn mở mà bạn cài đặt trên máy chủ GraphQL của mình để tạo ra một cổng API RESTful và có thể định cấu hình đầy đủ. Sử dụng GraphQL để REST.

Hướng dẫn cách làm thế nào

Hãy để chúng tôi tạo một hướng dẫn từng bước ngắn về cách tạo API RESTful.

Bước 1: npm cài đặt gói `sofa-api` và thêm dòng mã sau:

Bước 2: Đi REST trên Sofa, bạn đã hoàn thành.

Kamil Kisiela đã thêm Sofa vào triển khai API SpaceX GraphQL của Carlos Rufo, trong một cam kết duy nhất.

Kiểm tra các điểm cuối REST được tạo đầy đủ, tài liệu trực tiếp Swagger, trình soạn thảo GraphiQL và GraphiQL-Explorer!

Nhân tiện, những gì bạn thấy ở đây là API REST, được tạo trên đầu API GraphQL, được tạo trên đầu trang API API khác.

Tại sao bạn làm điều đó cho!?!?

Dần dần di chuyển từ các triển khai REST cũ

Đây thực sự là một hướng tốt để đi. Trong nhiều công ty chúng tôi hợp tác, họ đã tạo các lớp API REST bằng cách sử dụng công nghệ cũ trên các dịch vụ web ban đầu của họ.

Nhưng các triển khai REST đó có vấn đề (vì tất cả các lý do rõ ràng mà mọi người chọn chuyển sang GraphQL).

Vì vậy, cách của chúng tôi là tạo ra các triển khai GraphQL trên các lớp REST đó, di chuyển các máy khách đến các triển khai đó và sau đó loại bỏ dần lớp RESTful cũ và gọi trực tiếp các dịch vụ.

Việc sử dụng Sofa đã giúp những chuyển đổi đó nhanh hơn nhiều vì chúng tôi có thể cung cấp cho tất cả các khách hàng hiện tại để chuyển sang triển khai GraphQL mà không thực sự sử dụng chính GraphQL. Chúng tôi chỉ đơn giản đưa ra các điểm cuối REST giống nhau trên đầu GraphQL và chúng đang di chuyển đến lớp của chúng tôi một cách vui vẻ vì chúng tôi có thể đáp ứng tất cả các yêu cầu của chúng và các điểm cuối REST tùy chỉnh nhanh hơn nhiều so với triển khai REST cũ, ban đầu.

Cho tôi biết thêm chi tiết

Sofa sử dụng Express theo mặc định nhưng bạn có thể sử dụng bất kỳ khung máy chủ nào khác. Sofa cũng là bất khả thi của máy chủ GraphQL.

Truy cập trang web Sofa để tìm tài liệu và kho lưu trữ Github để báo cáo các vấn đề và trợ giúp.

Sofa hoạt động như thế nào?

Dưới mui xe, Sofa biến từng trường Loại truy vấn và Đột biến thành các tuyến. Nhóm tuyến đầu tiên chỉ khả dụng thông qua phương thức GET, mặt khác là nhận POST.

Sofa sử dụng GraphQL VÒNG AST để tạo ra một hoạt động với tất cả các biến có thể (ngay cả những biến được lồng sâu) và biết chính xác những gì cần tìm nạp. Sau đó, nó chuyển đổi cơ thể yêu cầu thành các biến hoạt động và thực hiện nó theo Schema. Nó xảy ra cục bộ, nhưng nó cũng có thể sử dụng Máy chủ GraphQL bên ngoài hoặc thậm chí là Apollo Link.

Ngay bây giờ Sofa có hỗ trợ tích hợp cho Express nhưng nó hoàn toàn có thể sử dụng một khung khác. Khái niệm chính vẫn giống hệt nhau nên chỉ có cách chúng tôi xử lý yêu cầu khác nhau giữa các lần triển khai máy chủ khác nhau.

Đăng ký GraphQL như Webhooks?

Cách thức hoạt động đơn giản, bạn bắt đầu đăng ký bằng cách gọi một tuyến đường đặc biệt và bạn nhận được một ID duy nhất mà sau này có thể được sử dụng để cập nhật hoặc thậm chí dừng đăng ký. Đăng ký là Webhooks. Sofa biết chính xác khi có một sự kiện thậm chí xảy ra trên API của bạn và thông báo cho bạn thông qua điểm cuối mà bạn đã chỉ định đăng ký.

Mô hình / Tài nguyên?

Trong một số trường hợp, bạn không muốn lộ toàn bộ đối tượng nhưng chỉ là id của nó. Làm thế nào bạn có thể làm điều đó với Sofa? Bạn cần phải có hai truy vấn. Người đầu tiên phải trả về một thực thể duy nhất chỉ dựa trên id của nó (đó sẽ là một đối số) và thực thể thứ hai sẽ giải quyết một danh sách các thực thể đó. Ngoài ra, tên phải khớp, ví dụ: tài nguyên có tên Người dùng nên có hai truy vấn: user (id: ID): Người dùng và người dùng: [Người dùng]. Khá nhiều điều tương tự bạn sẽ làm với REST.

loại Truy vấn {
  người dùng (id: ID!): Người dùng
  người dùng: [Người dùng]
}

Trước khi Sofa tạo các tuyến đường, nó sẽ tìm các Mô hình đó và đăng ký chúng để khi các hoạt động được xây dựng, bạn không nên tìm nạp mọi thứ nhưng chỉ có một id.

Nhưng nếu bạn muốn tìm nạp toàn bộ một đối tượng nhưng chỉ ở một vài nơi thì sao?

Có một tùy chọn được gọi là bỏ qua cho phép bạn làm điều đó. Bạn chỉ cần vượt qua một đường dẫn mà bạn muốn ghi đè hành vi mặc định.

Đưa ra lược đồ bên dưới, bạn sẽ chỉ nhận được id tác giả.

loại Sách {
  tôi đã làm
  tiêu đề: Chuỗi!
  tác giả: Người dùng!
}
mở rộng loại Truy vấn {
  sách (id: ID!): Sách
  sách: [Sách]
}

Bỏ qua: ['Book. Tác giả'] bạn kết thúc với toàn bộ đối tượng Người dùng.

ghế sô pha({
  ...,
  bỏ qua: ['Book. Tác giả'],
})

Swagger và OpenAPI

Nhờ hệ thống loại GraphQL, Sofa có thể tạo tài liệu luôn cập nhật cho API REST của bạn. Ngay bây giờ chúng tôi hỗ trợ Swagger và thông số kỹ thuật OpenAPI của nó nhưng nó thực sự dễ dàng chấp nhận các thông số kỹ thuật khác nhau.

Tóm lược

sofa-api giúp tạo API RESTful cực kỳ dễ dàng với tất cả các thực tiễn tốt nhất về REST từ máy chủ GraphQL sử dụng tất cả sức mạnh của nó.

Ngừng lãng phí cuộc sống của bạn để tranh luận về REST vs GraphQL - Hãy làm việc hiệu quả, nhận được lợi ích của cả hai thế giới và hướng tới tương lai phát triển API.

Tôi hy vọng điều này sẽ trở thành bài viết REST so với GraphQL cuối cùng trên mạng. nếu bạn nghĩ rằng nó đã thắng được, hãy bình luận với trường hợp sử dụng và để cho bạn dùng thử!

Cảm ơn Kamil Kisiela đã làm việc với tôi về điều này và biến thư viện này thành hiện thực!

Theo dõi chúng tôi trên GitHub và Medium, chúng tôi dự định sẽ phát hành thêm nhiều bài đăng trong vài tuần tới về những gì chúng tôi đã học được bằng cách sử dụng GraphQL trong những năm gần đây.