Cập nhật từ nguồn

Một đặc tả API luôn tiến hóa. Nhập lại và ghi đè tất cả sẽ làm mất các điều chỉnh của bạn; nhập lại vào bên cạnh thì tạo ra bản trùng. Restorm làm điều thứ ba: nó tính phần khác biệt.

Cơ chế hoạt động

Mỗi lần nhập thành công đều ghi lại một dấu vân tay của nguồn lên thư mục biến vừa được tạo. Nút Làm mới của thư mục sẽ lấy lại nguồn, so sánh các dấu vân tay và áp dụng những điểm khác biệt thay vì làm lại từ đầu:

• các thao tác mới được thêm vào, đúng chỗ mà một lần nhập mới sẽ đặt chúng;
• các thao tác bị sửa đổi được bổ sung tham số theo những gì đặc tả thêm vào;
• các thao tác mà đặc tả đánh dấu là lỗi thời được báo hiệu và hiện ra mờ đi trong cây;
• các thao tác đã biến mất khỏi nguồn được báo là đã bị gỡ bỏ và hiện ra gạch ngang — chúng vẫn chạy được và không bao giờ bị xóa;
• các sửa đổi của bạn được giữ nguyên: tên, phương thức, URL và những giá trị bạn đã nhập không bao giờ bị ghi đè.

Nguyên tắc: đặc tả có thẩm quyền trên những gì nó mô tả, còn bạn có thẩm quyền trên phần còn lại.

Toàn bộ trình tự — nút nằm ở đâu, trình hướng dẫn cho thấy gì trước khi áp dụng, tài liệu sẽ ra sao — được mô tả trong Truy cập và cập nhật tài liệu của một API đã nhập.

Chỉ dành cho các lần nhập bằng URL

Việc đồng bộ lại giả định rằng Restorm biết được nguồn. Chỉ những lần nhập thực hiện từ một URL mới ghi lại nguồn; một lần nhập từ tệp hoặc bằng cách dán nội dung thì không đồng bộ lại được, ngay cả khi định dạng của nó có tên trong danh sách dưới đây.

Các định dạng đồng bộ lại được

Có mười hai định dạng:

• OpenAPI 3.x
• Swagger 2.0 (cùng trang với định dạng trên, nhưng ở đây được tính riêng: cả hai đều có logic đồng bộ lại của riêng mình)
• GraphQL (SDL)
• gRPC — tệp .proto và phản chiếu máy chủ
• SOAP / WSDL
• OData
• AsyncAPI
• Postman
• Insomnia
• Bruno
• OpenRPC
• Smithy

Các định dạng không đồng bộ lại được

HAR, cURL, PowerShell, REST Client, Thunder Client, Paw, HTTPie, RAML, WADL, Thrift, TypeSpec, API Blueprint, tRPC.

Với những định dạng này, một lần nhập mới sẽ tạo ra một cây mới: bạn tự đối chiếu hai cây, hoặc nhập vào một thư mục riêng.

Trường hợp đặc biệt: gRPC bằng phản chiếu

Một yêu cầu gRPC được nhập bằng phản chiếu có một nút Làm mới từ phản chiếu ngay trên tab của nó: đó là con đường ngắn nhất khi một dịch vụ thay đổi trong quá trình phát triển.