You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apisix.apache.org by Xiran Liu <li...@apache.org> on 2021/08/25 10:15:55 UTC
Re: [DISCUSS] support RESTful API for Apache APISIX projects
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 <sh...@gmail.com> wrote:
> Hi Zhiyuna,
>
> Yes. step by step. cheers!
>
> On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <ju...@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 <sh...@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 <ju...@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 <zc...@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 (
> > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > wenming@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 <st...@apache.org> 于2021年7月21日周三 下午11:18写道：
> > > > > > > > >> > >
> > > > > > > > >> > > > Agree +1.
> > > > > > > > >> > > > And I think we should maintain the `code` filed and
> > > > maintain
> > > > > > the
> > > > > > > > >> doc of
> > > > > > > > >> > > > API.
> > > > > > > > >> > > >
> > > > > > > > >> > >
> > > > > > > > >> >
> > > > > > > > >>
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by Zhiyuan Ju <ju...@apache.org>.
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 <li...@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 <li...@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 <ch...@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 <ju...@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 <li...@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 <ju...@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 <li...@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.madura@gmail.com>
> > > > > > > > wrote:
> > > > > > > > > Hi Zhiyuna,
> > > > > > > > >
> > > > > > > > > Yes. step by step. cheers!
> > > > > > > > >
> > > > > > > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <
> juzhiyuan@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 <sh...@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 <
> > > > > > juzhiyuan@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 <sh...@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 <
> > > > > juzhiyuan@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 <zc...@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 (
> > > > > > > > > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > > > > > > > > wenming@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 <st...@apache.org>
> 于2021年7月21日周三
> > > > > > > > 下午11:18写道：
> > > > > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > > > > > > > >> > > > And I think we should maintain the
> `code`
> > > > > > filed
> > > > > > > > and
> > > > > > > > > > > > maintain
> > > > > > > > > > > > > > the
> > > > > > > > > > > > > > > > >> doc of
> > > > > > > > > > > > > > > > >> > > > API.
> > > > > > > > > > > > > > > > >> > > >
> > > > > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > > > > >> >
> > > > > > > > > > > > > > > > >>
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > > --
> > > > > > > 来自 琚致远
> > > > > > >
> > > > > >
> > > > > --
> > > > > 来自 琚致远
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by Xiran Liu <li...@apache.org>.
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 <li...@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 <ch...@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 <ju...@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 <li...@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 <ju...@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 <li...@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.madura@gmail.com>
> > > > > > > wrote:
> > > > > > > > Hi Zhiyuna,
> > > > > > > >
> > > > > > > > Yes. step by step. cheers!
> > > > > > > >
> > > > > > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <
> > > > > juzhiyuan@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 <sh...@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 <
> > > > juzhiyuan@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 <zc...@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 (
> > > > > > > > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > > > > > > > wenming@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 <st...@apache.org> 于2021年7月21日周三
> > > > > > > 下午11:18写道：
> > > > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > > > > > > >> > > > And I think we should maintain the `code`
> > > > > filed
> > > > > > > and
> > > > > > > > > > > maintain
> > > > > > > > > > > > > the
> > > > > > > > > > > > > > > >> doc of
> > > > > > > > > > > > > > > >> > > > API.
> > > > > > > > > > > > > > > >> > > >
> > > > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > > > >> >
> > > > > > > > > > > > > > > >>
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > > --
> > > > > > 来自 琚致远
> > > > > >
> > > > >
> > > > --
> > > > 来自 琚致远
> > > >
> > >
> >
>
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by Xiran Liu <li...@apache.org>.
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 <ch...@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 <ju...@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 <li...@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 <ju...@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 <li...@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.madura@gmail.com>
> > > > > > wrote:
> > > > > > > Hi Zhiyuna,
> > > > > > >
> > > > > > > Yes. step by step. cheers!
> > > > > > >
> > > > > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <
> > > > juzhiyuan@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 <sh...@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 <
> > > juzhiyuan@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 <zc...@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 (
> > > > > > > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > > > > > > wenming@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 <st...@apache.org> 于2021年7月21日周三
> > > > > > 下午11:18写道：
> > > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > > > > > >> > > > And I think we should maintain the `code`
> > > > filed
> > > > > > and
> > > > > > > > > > maintain
> > > > > > > > > > > > the
> > > > > > > > > > > > > > >> doc of
> > > > > > > > > > > > > > >> > > > API.
> > > > > > > > > > > > > > >> > > >
> > > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > > >> >
> > > > > > > > > > > > > > >>
> > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > > --
> > > > > 来自 琚致远
> > > > >
> > > >
> > > --
> > > 来自 琚致远
> > >
> >
>
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by Xiran Liu <li...@apache.org>.
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 <ch...@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 <ju...@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 <li...@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 <ju...@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 <li...@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.madura@gmail.com>
> > > > > wrote:
> > > > > > Hi Zhiyuna,
> > > > > >
> > > > > > Yes. step by step. cheers!
> > > > > >
> > > > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <
> > > juzhiyuan@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 <sh...@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 <
> > juzhiyuan@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 <zc...@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 (
> > > > > > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > > > > > wenming@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 <st...@apache.org> 于2021年7月21日周三
> > > > > 下午11:18写道：
> > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > > > > >> > > > And I think we should maintain the `code`
> > > filed
> > > > > and
> > > > > > > > > maintain
> > > > > > > > > > > the
> > > > > > > > > > > > > >> doc of
> > > > > > > > > > > > > >> > > > API.
> > > > > > > > > > > > > >> > > >
> > > > > > > > > > > > > >> > >
> > > > > > > > > > > > > >> >
> > > > > > > > > > > > > >>
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > > --
> > > > 来自 琚致远
> > > >
> > >
> > --
> > 来自 琚致远
> >
>
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by JunXu Chen <ch...@apache.org>.
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 <ju...@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 <li...@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 <ju...@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 <li...@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.madura@gmail.com>
> > > > wrote:
> > > > > Hi Zhiyuna,
> > > > >
> > > > > Yes. step by step. cheers!
> > > > >
> > > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <
> > juzhiyuan@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 <sh...@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 <
> juzhiyuan@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 <zc...@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 (
> > > > > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > > > > wenming@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 <st...@apache.org> 于2021年7月21日周三
> > > > 下午11:18写道：
> > > > > > > > > > > > >> > >
> > > > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > > > >> > > > And I think we should maintain the `code`
> > filed
> > > > and
> > > > > > > > maintain
> > > > > > > > > > the
> > > > > > > > > > > > >> doc of
> > > > > > > > > > > > >> > > > API.
> > > > > > > > > > > > >> > > >
> > > > > > > > > > > > >> > >
> > > > > > > > > > > > >> >
> > > > > > > > > > > > >>
> > > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > > --
> > > 来自 琚致远
> > >
> >
> --
> 来自 琚致远
>
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by Zhiyuan Ju <ju...@apache.org>.
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 <li...@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 <ju...@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 <li...@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.madura@gmail.com>
> > > wrote:
> > > > Hi Zhiyuna,
> > > >
> > > > Yes. step by step. cheers!
> > > >
> > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <
> juzhiyuan@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 <sh...@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 <juzhiyuan@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 <zc...@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 (
> > > > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > > > wenming@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 <st...@apache.org> 于2021年7月21日周三
> > > 下午11:18写道：
> > > > > > > > > > > >> > >
> > > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > > >> > > > And I think we should maintain the `code`
> filed
> > > and
> > > > > > > maintain
> > > > > > > > > the
> > > > > > > > > > > >> doc of
> > > > > > > > > > > >> > > > API.
> > > > > > > > > > > >> > > >
> > > > > > > > > > > >> > >
> > > > > > > > > > > >> >
> > > > > > > > > > > >>
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> > --
> > 来自 琚致远
> >
>
--
来自 琚致远
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by Xiran Liu <li...@apache.org>.
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 <ju...@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 <li...@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 <sh...@gmail.com>
> > wrote:
> > > Hi Zhiyuna,
> > >
> > > Yes. step by step. cheers!
> > >
> > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <ju...@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 <sh...@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 <ju...@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 <zc...@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 (
> > > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > > wenming@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 <st...@apache.org> 于2021年7月21日周三
> > 下午11:18写道：
> > > > > > > > > > >> > >
> > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > >> > > > And I think we should maintain the `code` filed
> > and
> > > > > > maintain
> > > > > > > > the
> > > > > > > > > > >> doc of
> > > > > > > > > > >> > > > API.
> > > > > > > > > > >> > > >
> > > > > > > > > > >> > >
> > > > > > > > > > >> >
> > > > > > > > > > >>
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
> --
> 来自 琚致远
>
Re: [DISCUSS] support RESTful API for Apache APISIX projects
Posted by Zhiyuan Ju <ju...@apache.org>.
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 <li...@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 <sh...@gmail.com>
> wrote:
> > Hi Zhiyuna,
> >
> > Yes. step by step. cheers!
> >
> > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <ju...@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 <sh...@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 <ju...@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 <sh...@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 <ju...@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 <zc...@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 (
> > > > > zhangjintao9020@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 <ju...@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 <ju...@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 <we...@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 <ch...@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 <
> > > wenming@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 <st...@apache.org> 于2021年7月21日周三
> 下午11:18写道：
> > > > > > > > > >> > >
> > > > > > > > > >> > > > Agree +1.
> > > > > > > > > >> > > > And I think we should maintain the `code` filed
> and
> > > > > maintain
> > > > > > > the
> > > > > > > > > >> doc of
> > > > > > > > > >> > > > API.
> > > > > > > > > >> > > >
> > > > > > > > > >> > >
> > > > > > > > > >> >
> > > > > > > > > >>
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
--
来自 琚致远