Since both zhiyuan and junxu perfer to this style ```text POST /apisix/admin/routes ``` I tried to read more references:
* https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design * https://www.partech.nl/nl/publicaties/2020/07/9-trending-best-practices-for-rest-api-development# > In the REST model, you frequently apply POST requests to collections this viewpoint persuaded me, and this is also the way that is accepted by most people, we should follow it. Then I tried to list the entire Route module API in detail, and the goal is to serve as a sample of modifications to other modules, in order to make it easier to read, I submitted a Proposal in dashboard: https://github.com/apache/apisix-dashboard/issues/2105 looking forward to your opinion， thanks a lot * Fetch resource list Method and url ```text GET /apisix/admin/routes ``` Request parameters | name | type | location | required | description | | ------- | | page | int | Query | 否 | 指定页码 | | page_size | int | Query | 否 | 每页返回多少数据 | | name | tring | Query | 否 | 路由名称 | | uri | url | Query | 否 | 按照 URI 搜索 | | status | int | Query | 否 | 启用路由（默认启用），可选值：`1（启用）`、`0（不启用）`。 | | label | string | Query | 否 | 标签名称或值 | On 2021/08/26 02:41:58, JunXu Chen <chenju...@apache.org> wrote: > 2. create a route, POST PATCH PUT. and GET resource item info response > refer to this. > > ```text > POST /apisix/admin/route > ``` > > ------------------------------------------ > > I prefer to: > > ```text > POST /apisix/admin/routes > ``` > > > > On Wed, 25 Aug 2021 at 19:08, Zhiyuan Ju <juzhiy...@apache.org> wrote: > > > Waiting for others opinions, I prefer to keep using /routes here :) Maybe > > have a look at some popular sites like GitHub and Stripe? > > > > Xiran Liu <liuxi...@apache.org>于2021年8月25日 周三下午7:06写道： > > > > > Thanks zhiyuan~ > > > > > > 1. The singular and plural are involved here, POST would create a route > > > right, so I think route is better. > > > 2. sorry, this is a mistake, should omit /api here. > > > 3. yes, agree with total_count. > > > > > > > > > > > > On 2021/08/25 10:40:42, Zhiyuan Ju <juzhiy...@apache.org> wrote: > > > > Hi, > > > > > > > > I have some thoughts here: > > > > > > > > 1. We could use POST /apisix/admin/routes instead of /route, due to the > > > > previous one is more RESTful > > > > > > > > 2. It’s ok to omit the /api/ in the first case > > > > > > > > 3. Use list and total_count instead of items and total_size, more > > > > meaningful for me :) > > > > > > > > Xiran Liu <liuxi...@apache.org>于2021年8月25日 周三下午6:16写道： > > > > > > > > > Hi Community, > > > > > > > > > > It's been a while since the restful api discussion was updated. > > > > > > > > > > It seems that we have reached an agreement that we will use HTTP > > Status > > > > > code instead of the current response body param `code`, when the > > > request > > > > > got status 200, it will return the request data, and when it got > > > error, it > > > > > will return the error message in the response body. > > > > > > > > > > I tried to list the two method of Route Module in current > > Manager-api, > > > > > stand for two scenarios, focused on the response parameters, let's > > see > > > > > whether it meets agreement, > > > > > > > > > > 1. get list of all routes, all list request response refer to this. > > > > > > > > > > ```text > > > > > GET /apisix/admin/api/routes > > > > > ``` > > > > > Response: > > > > > > > > > > Status: 200 OK - application/json > > > > > > > > > > ```json > > > > > { > > > > > "items": [{"schema of the route"}], > > > > > "total_size": 1, > > > > > } > > > > > ``` > > > > > > > > > > Status: 500 Internal Server Error > > > > > > > > > > ```json > > > > > { > > > > > "message": "Internal Server Error" > > > > > } > > > > > ``` > > > > > > > > > > 2. create a route, POST PATCH PUT. and GET resource item info > > response > > > > > refer to this. > > > > > > > > > > ```text > > > > > POST /apisix/admin/route > > > > > ``` > > > > > Response: > > > > > > > > > > Status: 200 OK - application/json > > > > > > > > > > ```json > > > > > { > > > > > "name": "route1", > > > > > ...other route schema > > > > > } > > > > > ``` > > > > > Note: for the POST PUT PATCH method, will return the updated resource > > > > > schema, for the GET info method, will return the request item schema. > > > > > > > > > > Status: 500 Internal Server Error > > > > > > > > > > ```json > > > > > { > > > > > "message": "Internal Server Error" > > > > > } > > > > > ``` > > > > > > > > > > If we have no doubt about this style. I will go on to refine all the > > > > > interfaces of the route module and at the same time consistent > > > experience > > > > > with both Manager API and Admin API. > > > > > > > > > > Looking forward to your reply, thanks a lot > > > > > > > > > > > > > > > > > > > > > > > > > On 2021/07/27 08:56:58, Shyamal Madura Chinthaka < > > > shyamal.mad...@gmail.com> > > > > > wrote: > > > > > > Hi Zhiyuna, > > > > > > > > > > > > Yes. step by step. cheers! > > > > > > > > > > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <juzhiy...@apache.org> > > > wrote: > > > > > > > > > > > > > Got it, I would prefer to adjust the first revision and make it > > > > > RESTful. > > > > > > > HATEOAS may be the final version haha :) > > > > > > > > > > > > > > Best Regards! > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > > > > > > > > > > > > > > > > > > > > Shyamal Madura Chinthaka <shyamal.mad...@gmail.com> > > 于2021年7月27日周二 > > > > > > > 下午4:03写道： > > > > > > > > > > > > > > > Hi Zhiyuan, > > > > > > > > > > > > > > > > Good day to you and all! > > > > > > > > > > > > > > > > Yes, you are spot on. This eventually increases the robustness > > of > > > > > the API > > > > > > > > to decouple service client static awareness uses the > > > server-provided > > > > > > > links > > > > > > > > to dynamically discover available actions and access the > > > resources it > > > > > > > > needs. > > > > > > > > > > > > > > > > Regards, > > > > > > > > Shyamal > > > > > > > > > > > > > > > > On Tue, Jul 27, 2021 at 10:31 AM Zhiyuan Ju < > > > juzhiy...@apache.org> > > > > > > > wrote: > > > > > > > > > > > > > > > > > Hi, Shyamal, > > > > > > > > > > > > > > > > > > Just to make sure, do you mean you want the response body > > > including > > > > > > > > > something like `_herf` or `links` to other resources? > > > > > > > > > > > > > > > > > > ```json > > > > > > > > > { > > > > > > > > > "id" : 1, > > > > > > > > > "body" : "My first blog post", > > > > > > > > > "postdate" : "2015-05-30T21:41:12.650Z", > > > > > > > > > "_links" : { > > > > > > > > > "self": { "href": "http://blog.example.com/posts/1"; > > }, > > > > > > > > > "comments": { "href": " > > > > > > > http://blog.example.com/posts/1/comments > > > > > > > > ", > > > > > > > > > "totalcount" : 20 }, > > > > > > > > > "tags": { "href": " > > > http://blog.example.com/posts/1/tags"; } > > > > > > > > > } > > > > > > > > > } > > > > > > > > > ``` > > > > > > > > > > > > > > > > > > Best Regards! > > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > > > > > > > > > > > > > > > > > > > > > > > > > > Shyamal Madura Chinthaka <shyamal.mad...@gmail.com> > > > 于2021年7月27日周二 > > > > > > > > > 上午2:36写道： > > > > > > > > > > > > > > > > > > > Hi Team, > > > > > > > > > > > > > > > > > > > > +1 to rely on HTTP status code instead of the code in the > > > > > response > > > > > > > > body. > > > > > > > > > > > > > > > > > > > > This will take our burden of enforcing governance to > > > > > define/maintain > > > > > > > > > > additional code in the response body which will unlikely to > > > > > > > effectively > > > > > > > > > > override the HTTP status code. > > > > > > > > > > > > > > > > > > > > However - if possible - enriching the response of these > > APIs > > > to > > > > > adopt > > > > > > > > > > HATEOAS would be progressive immensely. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > Regards, > > > > > > > > > > Shyamal > > > > > > > > > > > > > > > > > > > > On Mon, Jul 26, 2021, 07:20 Zhiyuan Ju < > > juzhiy...@apache.org > > > > > > > > > wrote: > > > > > > > > > > > > > > > > > > > > > Hi, > > > > > > > > > > > > > > > > > > > > > > Users have 2 ways to use our product: Using Dashboard or > > > Call > > > > > API > > > > > > > > > > directly. > > > > > > > > > > > > > > > > > > > > > > We have JSONSchema checker on the backend, if users call > > > API > > > > > > > directly > > > > > > > > > and > > > > > > > > > > > check failed, it will return the JSONSchema error; if > > > users use > > > > > > > > > > Dashboard, > > > > > > > > > > > why not validate data on Web? So I think there has no > > need > > > to > > > > > add a > > > > > > > > > > > specific login code in the Response Body :) > > > > > > > > > > > > > > > > > > > > > > Best Regards! > > > > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > Chao Zhang <zchao1...@gmail.com> 于2021年7月26日周一 上午9:41写道： > > > > > > > > > > > > > > > > > > > > > > > HTTP status code will be fine if we don’t care the very > > > > > specific > > > > > > > > > error > > > > > > > > > > > > type. > > > > > > > > > > > > > > > > > > > > > > > > Chao Zhang > > > > > > > > > > > > https://github.com/tokers > > > > > > > > > > > > > > > > > > > > > > > > On July 25, 2021 at 17:34:40, Jintao Zhang ( > > > > > > > > > zhangjintao9...@gmail.com) > > > > > > > > > > > > wrote: > > > > > > > > > > > > > > > > > > > > > > > > I agree! > > > > > > > > > > > > At the same time, I also think that HTTP Status code > > > should > > > > > be > > > > > > > used > > > > > > > > > > > instead > > > > > > > > > > > > of the logical code field. > > > > > > > > > > > > > > > > > > > > > > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年7月25日周日 > > > 下午3:29写道： > > > > > > > > > > > > > > > > > > > > > > > > > Hi, > > > > > > > > > > > > > > > > > > > > > > > > > > Any further discussion on this mail? I'm going to > > list > > > all > > > > > APIs > > > > > > > > and > > > > > > > > > > > check > > > > > > > > > > > > > which part we should modify. > > > > > > > > > > > > > > > > > > > > > > > > > > Best Regards! > > > > > > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年7月22日周四 > > > 下午2:47写道： > > > > > > > > > > > > > > > > > > > > > > > > > > > I would prefer relying on Status Code instead of > > > `code` > > > > > > > > (actually > > > > > > > > > > > it's > > > > > > > > > > > > a > > > > > > > > > > > > > > manual logical and extendable code). > > > > > > > > > > > > > > > > > > > > > > > > > > > > Why not list all API cases then have a choice? > > > > > > > > > > > > > > > > > > > > > > > > > > > > Best Regards! > > > > > > > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > Ming Wen <wenm...@apache.org> 于2021年7月22日周四 > > > 下午12:36写道： > > > > > > > > > > > > > > > > > > > > > > > > > > > >> please give an example about i18n for a better > > > > > understanding > > > > > > > > > > > > > >> > > > > > > > > > > > > > >> Thanks, > > > > > > > > > > > > > >> Ming Wen, Apache APISIX PMC Chair > > > > > > > > > > > > > >> Twitter: _WenMing > > > > > > > > > > > > > >> > > > > > > > > > > > > > >> > > > > > > > > > > > > > >> JunXu Chen <chenju...@apache.org> 于2021年7月22日周四 > > > > > 上午11:36写道： > > > > > > > > > > > > > >> > > > > > > > > > > > > > >> > Agree +1 > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > I think we still need to keep the `code` field. > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > The FE needs to implement i18n according to it. > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > Unless `message` is semantic and can be used as > > a > > > key > > > > > of > > > > > > > > i18n. > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > On Thu, 22 Jul 2021 at 00:02, Ming Wen < > > > > > > > wenm...@apache.org> > > > > > > > > > > > wrote: > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > > I don't think the `code` filed is useful, HTTP > > > > > response > > > > > > > > code > > > > > > > > > > is > > > > > > > > > > > > > >> enough. > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > >> > > Thanks, > > > > > > > > > > > > > >> > > Ming Wen, Apache APISIX PMC Chair > > > > > > > > > > > > > >> > > Twitter: _WenMing > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > >> > > Peter Zhu <sta...@apache.org> 于2021年7月21日周三 > > > > > 下午11:18写道： > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > >> > > > Agree +1. > > > > > > > > > > > > > >> > > > And I think we should maintain the `code` > > > filed > > > > > and > > > > > > > > > maintain > > > > > > > > > > > the > > > > > > > > > > > > > >> doc of > > > > > > > > > > > > > >> > > > API. > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > 来自 琚致远 > > > > > > > > > -- > > 来自 琚致远 > > >
