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