官术网_书友最值得收藏!

Handling message versioning in REST

All services change over time, mainly because of new business requirements. More often than not, this includes changes to the entity structure.

Following are several options available to handle entity versioning:

  • URL versioning: Here the URL determines the version that is to be returned. This option seems to be the most common method used, although this goes against the RESTful nature of the URL, which expresses the resource. Although this provides a very simple mechanism for versioning, it requires the server to maintain multiple versions of the URL even though you are fetching the same information.

    HTTP GET: https://my_rest_service.com/api/v2/account/10043

  • Query string versioning: This option appends the required version number to the query string. The disadvantage of using this method is that some browsers and Internet Service Providers (ISPs) do not cache response messages when the request URL includes a query string.

    HTTP GET:

    https://my_rest_service.com/api/account/10043?version=2
  • Custom header versioning: This option adds a custom property to the request header and requires the client to append the custom property with each server request.

    HTTP GET: https://my_rest_service.com/api/account/10043

    X-api-version = 2
    Note

    Normally, custom header properties are prefixed with X, although there are no standards on the correct naming convention.

  • Media type versioning: This method is more in line with the REST specifications. The version is specified in the accept header property of request headers.

    HTTP GET:

    https://my_rest_service.com/api/account/10043
  • Accept: application/vnd. my_rest_service -v2.0+json, application/vnd.account+json

    The appended second part /vnd.account+json of the my_rest_service accept header informs the service to return any version if version 2.0 cannot be found. Also the +json keyword informs the server to return the response as JSON.

    To request different versions of the account object, set the accept header as follows:

    1.0: vnd. my_rest_service -v1.0+json
    1.1: vnd. my_rest_service -v1.1+json
    2.0: vnd. my_rest_service -v2.0+json

Unfortunately, there is no silver bullet to resolve which option to use as there are pros and cons for each one. The custom header and media type versioning strategy, require the server to examine these properties for every request in order to determine which entity version to return. The client also needs to configure the header properties with each request. The other method of using URL versioning or query string versioning is cache friendly to browsers and ISPs. However, this is not the purest form of creating a RESTful API.

The bottom line comes down to who will be consuming your services and what will be their preferred method. Most of the early adopters of REST-style services used the URL versioning strategy.

主站蜘蛛池模板: 南涧| 民县| 怀仁县| 乌拉特中旗| 阿鲁科尔沁旗| 辽宁省| 枞阳县| 布尔津县| 东源县| 勃利县| 奉化市| 利津县| 临沭县| 嘉义市| 大厂| 汾阳市| 红原县| 河西区| 溧阳市| 德钦县| 石门县| 渭南市| 大洼县| 普定县| 漾濞| 常山县| 盐山县| 漯河市| 广元市| 阜新市| 乐陵市| 鄱阳县| 大余县| 灵宝市| 平和县| 临洮县| 陇西县| 吐鲁番市| 子长县| 吕梁市| 溧水县|