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

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.

主站蜘蛛池模板: 牙克石市| 南溪县| 彭州市| 汤原县| 新沂市| 齐齐哈尔市| 澄城县| 星子县| 巴林右旗| 阳新县| 武邑县| 连城县| 宁陵县| 仁怀市| 开平市| 伊宁县| 建昌县| 玛纳斯县| 肃北| 来宾市| 库伦旗| 洛浦县| 山丹县| 临安市| 普格县| 淳安县| 黎平县| 类乌齐县| 渭源县| 房产| 台前县| 洱源县| 连城县| 营山县| 平乡县| 漳平市| 福泉市| 上杭县| 抚顺市| 临汾市| 永年县|