Agree, only one thing: We'd better use 201 for POST Request, but 200 makes sense to me as well :)
Best Regards! @ Zhiyuan Ju <https://github.com/juzhiyuan> Xiran Liu <liuxi...@apache.org> 于2021年9月13日周一 上午10:42写道： > Hi community, > > The Route API restful transformation has been discussed for some time, let > me summarize the design options > > * Reorganized Route API List > > | Method | Request URI | Description > | > | ------ | -------------------------------- | > -------------------------------------- | > | GET | /apisix/admin/routes | Fetch resource list > | > | GET | /apisix/admin/routes/{id} | Fetch resource by id > | > | POST | /apisix/admin/routes | Create resource > | > | DELETE | /apisix/admin/routes/{id} | Remove resource by id > | > | PUT | /apisix/admin/routes/{id} | Update/Create resource by > id | > | PATCH | /apisix/admin/routes/{id} | Update resource by id > | > | PUT | /apisix/admin/routes/{id}/{path} | Update specified attribute > though path | > > differences are: > > - change PATCH /apisix/admin/routes/{id}/{path} to PUT > /apisix/admin/routes/{id}/{path}, the reason: when user use this API they > can easier update the whole specified path in the route, refer to > https://en.wikipedia.org/wiki/Patch_verb, PUT method is more suitable. > > * Simplify request parameters > > only keep uris, remove uri, keep hosts, remove host, keep remote_addrs, > remove remote_addr. since uris/hosts/remote_addrs contains > uri/host/remote_addr, there is no need to keep two of them to Increase the > difficulty of choice for users > > * Uniform response parameter format > > - for GET /apisix/admin/routes returns HTTP code 200 and response body as > follows > ```json > { > "items":[{}], > "total_size": 1, > } > ``` > - for > GET /apisix/admin/routes, > POST /apisix/admin/routes, > PUT /apisix/admin/routes/{id} > PATCH /apisix/admin/routes/{id} > PUT /apisix/admin/routes/{id}/{path} > > returns HTTP code 200 and response body as follows > ```json > { > ...route parameters, > } > ``` > - for DELETE /apisix/admin/routes/{id} only returns HTTP code 200 > - when error occurs, it will return HTTP code 4xx and response body as > follows > ```json > { > "message": "xxxx" > } > ``` > > see https://github.com/apache/apisix-dashboard/issues/2105 for more > details > > what do you think? Looking forward to your reply, thanks a lot > > On 2021/08/31 00:50:11, Xiran Liu <liuxi...@apache.org> wrote: > > Sorry for some draft text was left in the previous email, update them to > make it easier to follow the main content > > > > 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 > > > > > > > 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. > > > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > > > >> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > > 来自 琚致远 > > > > > > > > > > > > > > > > > > -- > > > > > 来自 琚致远 > > > > > > > > > > > > > > >
