Waiting for others opinions, I prefer to keep using /routes here :) Maybe
have a look at some popular sites like GitHub and Stripe?

Xiran Liu <liuxi...@apache.org>于2021年8月25日 周三下午7:06写道:

> Thanks zhiyuan~
>
> 1. The singular and plural are involved here, POST would create a route
> right, so I think route is better.
> 2. sorry, this is a mistake, should omit /api here.
> 3. yes, agree with total_count.
>
>
>
> On 2021/08/25 10:40:42, Zhiyuan Ju <juzhiy...@apache.org> wrote:
> > Hi,
> >
> > I have some thoughts here:
> >
> > 1. We could use POST /apisix/admin/routes instead of /route, due to the
> > previous one is more RESTful
> >
> > 2. It’s ok to omit the /api/ in the first case
> >
> > 3. Use list and total_count instead of items and total_size, more
> > meaningful for me :)
> >
> > Xiran Liu <liuxi...@apache.org>于2021年8月25日 周三下午6:16写道:
> >
> > > Hi Community,
> > >
> > > It's been a while since the restful api discussion was updated.
> > >
> > > It seems that we have reached an agreement that we will use HTTP Status
> > > code instead of the current response body param `code`, when the
> request
> > > got status 200, it will return the request data, and when it got
> error, it
> > > will return the error message in the response body.
> > >
> > > I tried to list the two method of Route Module in current Manager-api,
> > > stand for two scenarios, focused on the response parameters, let's see
> > > whether it meets agreement,
> > >
> > > 1. get list of all routes, all list request response refer to this.
> > >
> > > ```text
> > > GET /apisix/admin/api/routes
> > > ```
> > > Response:
> > >
> > > Status: 200 OK - application/json
> > >
> > > ```json
> > >   {
> > >      "items": [{"schema of the route"}],
> > >      "total_size": 1,
> > >   }
> > > ```
> > >
> > > Status: 500 Internal Server Error
> > >
> > > ```json
> > >   {
> > >       "message": "Internal Server Error"
> > >   }
> > > ```
> > >
> > > 2. create a route, POST PATCH PUT. and GET resource item info response
> > > refer to this.
> > >
> > > ```text
> > > POST /apisix/admin/route
> > > ```
> > > Response:
> > >
> > > Status: 200 OK - application/json
> > >
> > > ```json
> > >   {
> > >      "name": "route1",
> > >      ...other route schema
> > >   }
> > > ```
> > > Note: for the POST PUT PATCH method, will return the updated resource
> > > schema, for the GET info method, will return the request item schema.
> > >
> > > Status: 500 Internal Server Error
> > >
> > > ```json
> > >   {
> > >       "message": "Internal Server Error"
> > >   }
> > > ```
> > >
> > > If we have no doubt about this style. I will go on to refine all the
> > > interfaces of the route module and at the same time consistent
> experience
> > > with both Manager API and Admin API.
> > >
> > > Looking forward to your reply, thanks a lot
> > >
> > >
> > >
> > >
> > > On 2021/07/27 08:56:58, Shyamal Madura Chinthaka <
> shyamal.mad...@gmail.com>
> > > wrote:
> > > > Hi Zhiyuna,
> > > >
> > > > Yes. step by step. cheers!
> > > >
> > > > On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <juzhiy...@apache.org>
> wrote:
> > > >
> > > > > Got it, I would prefer to adjust the first revision and make it
> > > RESTful.
> > > > > HATEOAS may be the final version haha :)
> > > > >
> > > > > Best Regards!
> > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > >
> > > > >
> > > > > Shyamal Madura Chinthaka <shyamal.mad...@gmail.com> 于2021年7月27日周二
> > > > > 下午4:03写道:
> > > > >
> > > > > > Hi  Zhiyuan,
> > > > > >
> > > > > > Good day to you and all!
> > > > > >
> > > > > > Yes, you are spot on. This eventually increases the robustness of
> > > the API
> > > > > > to decouple service client static awareness uses the
> server-provided
> > > > > links
> > > > > > to dynamically discover available actions and access the
> resources it
> > > > > > needs.
> > > > > >
> > > > > > Regards,
> > > > > > Shyamal
> > > > > >
> > > > > > On Tue, Jul 27, 2021 at 10:31 AM Zhiyuan Ju <
> juzhiy...@apache.org>
> > > > > wrote:
> > > > > >
> > > > > > > Hi, Shyamal,
> > > > > > >
> > > > > > > Just to make sure, do you mean you want the response body
> including
> > > > > > > something like `_herf` or `links` to other resources?
> > > > > > >
> > > > > > > ```json
> > > > > > > {
> > > > > > >     "id" : 1,
> > > > > > >     "body" : "My first blog post",
> > > > > > >     "postdate" : "2015-05-30T21:41:12.650Z",
> > > > > > >     "_links" : {
> > > > > > >         "self": { "href": "http://blog.example.com/posts/1"; },
> > > > > > >         "comments": { "href": "
> > > > > http://blog.example.com/posts/1/comments
> > > > > > ",
> > > > > > > "totalcount" : 20 },
> > > > > > >         "tags": { "href": "
> http://blog.example.com/posts/1/tags"; }
> > > > > > >     }
> > > > > > > }
> > > > > > > ```
> > > > > > >
> > > > > > > Best Regards!
> > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > > > >
> > > > > > >
> > > > > > > Shyamal Madura Chinthaka <shyamal.mad...@gmail.com>
> 于2021年7月27日周二
> > > > > > > 上午2:36写道:
> > > > > > >
> > > > > > > > Hi Team,
> > > > > > > >
> > > > > > > > +1 to rely on HTTP status code instead of the code in the
> > > response
> > > > > > body.
> > > > > > > >
> > > > > > > > This will take our burden of enforcing governance to
> > > define/maintain
> > > > > > > > additional code in the response body which will unlikely to
> > > > > effectively
> > > > > > > > override the HTTP status code.
> > > > > > > >
> > > > > > > > However - if possible - enriching the response of these APIs
> to
> > > adopt
> > > > > > > > HATEOAS would be progressive immensely.
> > > > > > > >
> > > > > > > >
> > > > > > > > Regards,
> > > > > > > > Shyamal
> > > > > > > >
> > > > > > > > On Mon, Jul 26, 2021, 07:20 Zhiyuan Ju <juzhiy...@apache.org
> >
> > > wrote:
> > > > > > > >
> > > > > > > > > Hi,
> > > > > > > > >
> > > > > > > > > Users have 2 ways to use our product: Using Dashboard or
> Call
> > > API
> > > > > > > > directly.
> > > > > > > > >
> > > > > > > > > We have JSONSchema checker on the backend, if users call
> API
> > > > > directly
> > > > > > > and
> > > > > > > > > check failed, it will return the JSONSchema error; if
> users use
> > > > > > > > Dashboard,
> > > > > > > > > why not validate data on Web? So I think there has no need
> to
> > > add a
> > > > > > > > > specific login code in the Response Body :)
> > > > > > > > >
> > > > > > > > > Best Regards!
> > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > Chao Zhang <zchao1...@gmail.com> 于2021年7月26日周一 上午9:41写道:
> > > > > > > > >
> > > > > > > > > > HTTP status code will be fine if we don’t care the very
> > > specific
> > > > > > > error
> > > > > > > > > > type.
> > > > > > > > > >
> > > > > > > > > > Chao Zhang
> > > > > > > > > > https://github.com/tokers
> > > > > > > > > >
> > > > > > > > > > On July 25, 2021 at 17:34:40, Jintao Zhang (
> > > > > > > zhangjintao9...@gmail.com)
> > > > > > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > I agree!
> > > > > > > > > > At the same time, I also think that HTTP Status code
> should
> > > be
> > > > > used
> > > > > > > > > instead
> > > > > > > > > > of the logical code field.
> > > > > > > > > >
> > > > > > > > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年7月25日周日
> 下午3:29写道:
> > > > > > > > > >
> > > > > > > > > > > Hi,
> > > > > > > > > > >
> > > > > > > > > > > Any further discussion on this mail? I'm going to list
> all
> > > APIs
> > > > > > and
> > > > > > > > > check
> > > > > > > > > > > which part we should modify.
> > > > > > > > > > >
> > > > > > > > > > > Best Regards!
> > > > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年7月22日周四
> 下午2:47写道:
> > > > > > > > > > >
> > > > > > > > > > > > I would prefer relying on Status Code instead of
> `code`
> > > > > > (actually
> > > > > > > > > it's
> > > > > > > > > > a
> > > > > > > > > > > > manual logical and extendable code).
> > > > > > > > > > > >
> > > > > > > > > > > > Why not list all API cases then have a choice?
> > > > > > > > > > > >
> > > > > > > > > > > > Best Regards!
> > > > > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > > > Ming Wen <wenm...@apache.org> 于2021年7月22日周四
> 下午12:36写道:
> > > > > > > > > > > >
> > > > > > > > > > > >> please give an example about i18n for a better
> > > understanding
> > > > > > > > > > > >>
> > > > > > > > > > > >> Thanks,
> > > > > > > > > > > >> Ming Wen, Apache APISIX PMC Chair
> > > > > > > > > > > >> Twitter: _WenMing
> > > > > > > > > > > >>
> > > > > > > > > > > >>
> > > > > > > > > > > >> JunXu Chen <chenju...@apache.org> 于2021年7月22日周四
> > > 上午11:36写道:
> > > > > > > > > > > >>
> > > > > > > > > > > >> > Agree +1
> > > > > > > > > > > >> >
> > > > > > > > > > > >> >
> > > > > > > > > > > >> > I think we still need to keep the `code` field.
> > > > > > > > > > > >> >
> > > > > > > > > > > >> > The FE needs to implement i18n according to it.
> > > > > > > > > > > >> >
> > > > > > > > > > > >> > Unless `message` is semantic and can be used as a
> key
> > > of
> > > > > > i18n.
> > > > > > > > > > > >> >
> > > > > > > > > > > >> >
> > > > > > > > > > > >> >
> > > > > > > > > > > >> > On Thu, 22 Jul 2021 at 00:02, Ming Wen <
> > > > > wenm...@apache.org>
> > > > > > > > > wrote:
> > > > > > > > > > > >> >
> > > > > > > > > > > >> > > I don't think the `code` filed is useful, HTTP
> > > response
> > > > > > code
> > > > > > > > is
> > > > > > > > > > > >> enough.
> > > > > > > > > > > >> > >
> > > > > > > > > > > >> > > Thanks,
> > > > > > > > > > > >> > > Ming Wen, Apache APISIX PMC Chair
> > > > > > > > > > > >> > > Twitter: _WenMing
> > > > > > > > > > > >> > >
> > > > > > > > > > > >> > >
> > > > > > > > > > > >> > > Peter Zhu <sta...@apache.org> 于2021年7月21日周三
> > > 下午11:18写道:
> > > > > > > > > > > >> > >
> > > > > > > > > > > >> > > > Agree +1.
> > > > > > > > > > > >> > > > And I think we should maintain the `code`
> filed
> > > and
> > > > > > > maintain
> > > > > > > > > the
> > > > > > > > > > > >> doc of
> > > > > > > > > > > >> > > > API.
> > > > > > > > > > > >> > > >
> > > > > > > > > > > >> > >
> > > > > > > > > > > >> >
> > > > > > > > > > > >>
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> > --
> > 来自 琚致远
> >
>
-- 
来自 琚致远

Reply via email to