Định dạng khóa-giá trị 2 chiều mà Api Blueprint có thể hiểu được là gì?

Question

Tôi đang phát triển tài liệu api cho API tìm kiếm RESTful bằng cách sử dụng Api Blueprint. Tôi muốn để có thể vượt qua bộ lọc để API vì vậy tôi có thể lắp ráp:

filter[filtername1]=filtervalue1 
filter[filtername2]=filtervalue2 

mỗi câu hỏi này, tôi đang sử dụng phần trăm mã hóa dấu ngoặc vuông, nhưng không giống như câu hỏi này, nó không thể cho chúng tôi để mô tả mỗi có thể tên chính:

How to format hash-based parameters in the URL when creating Blueprint API doc?

tôi muốn tên chìa khóa để có biến, vì nó có thể là bất kỳ trường trong dữ liệu nguồn. Điều này có hiệu quả không?

## Key-Value-Test [/api/v1/keyvaluetest?term={term}&filter%5B{field_name}%5D={field_value}] 

+ term 
+ filter_field 
+ filter_value 

Có định dạng được đề xuất cho mảng hai chiều như thế này không? Dường như điều này không hoạt động trong Dredd vì + filter_field không thực sự khớp với filter[filter_field]

Answer 1

API Blueprint sử dụng URI Templates standard. Có nhiều cách để bày tỏ và mở rộng mảng (xem section 3.2.1), tuy nhiên, nó hy vọng "cách tiếp cận URI tiêu chuẩn", có nghĩa là URI sẽ được mở rộng như sau:

/api/v1/keyvaluetest?term=yourterm&filter=filtervalue1&filter=filtervalue2

mà là một "tiêu chuẩn" cách làm mảng, ngoại trừ ngôn ngữ web phổ biến nhất phổ biến theo cách của bạn vào năm 2000.

Các mẫu được thiết kế để mở rộng: cung cấp cho nó một loạt các biến và một chuỗi và bạn sẽ nhận được một chuỗi được định dạng đúng. Theo như tôi biết, không có "trận đấu hoang dã" (chèn các biến phù hợp với mẫu tại một vị trí nhất định trong chuỗi).

Giải pháp duy nhất tôi có thể nghĩ ra trong lĩnh vực của mẫu URL sẽ được lợi dụng sửa đổi lần nổ (xem composite values):

/api/v1/keyvaluetest{?keys*}

đó, cho mảng kết hợp các giá trị [(filter%5Bfiltername1%5D, filtervalue1), (filter%5Bfiltername2%5D, filtervalue2) ]nên mở rộng đúng.

Tuy nhiên, tôi không chắc chắn làm thế nào để xác định những người trong MSON như tôi không nghĩ rằng có một hỗ trợ cho "phím năng động" và tôi nghĩ rằng hầu hết các dụng cụ sẽ không xử lý nó (chưa).

Có thể worth asking.

Answer 2

Tôi sợ rằng API Blueprint và Apiary vẫn chưa cho phép các định nghĩa URL động này.

Blueprint API và Apiary chỉ cho phép URI Templates theo quy định tại RFC 6570

Template URI sau đây là không hợp lệ theo đó RFC

GET /resource?year={year}&month={month} 

Bạn có thể thay đổi URL để xác định giống như sau:

## Key-Value-Test [/api/v1/keyvaluetest{?term,field_name,field_value}] 

+ Parameters 
    + term: a 
    + field_name: b 
    + field_value: c 

có hai hãy cẩn thận với phương pháp này:

• Bạn chỉ có thể đặt một tên trường và giá trị trường cho các tham số. Nếu bạn muốn có thêm thông số trường, bạn phải mở rộng URL.
• Bạn phải thay đổi url API mà tôi không nghĩ bạn muốn.

Vui lòng bắt đầu yêu cầu tính năng tại http://support.apiary.io nếu bạn có.