How to introduce change in web api response payload structure without breaking existing integration

Question

In one of our existing .net core web api (REST) end point, one of its property value in response payload is email address which will be changed to alphanumeric id shortly. This change in response payload will break existing integration.

This breaking change impact can be addressed by introducing version to api saying that only v2 version will alphanumeric id in its response payload otherwise v1 version will keep rendering email address in its response payload but is there any other alternative solution to avoid broken existing integration even after introducing the change in existing response payload structure

Existing response payload structure:

{
  customerid: [email protected]
}

Future response payload structure:

{
  customerid: 1123acbd56
}

Sorry for the ignorance, can you explain bit more with sample please — 191180rk
– 191180rk, Commented Sep 10, 2020 at 16:20
JSON does not have a data type for email or alphanumeric values. From a client's perspective, both values are string. A client should never assume anything about the format of these values. customerid != email. This is a problem for the client if they are doing that. You will have to evaluate the weight of trying to support a client doing this. There are several possible solutions, several of which have already been provided. — Chris Martinez
– Chris Martinez, Commented Sep 16, 2020 at 20:38
please list out those several possible solutions you have mentioned above. — 191180rk
– 191180rk, Commented Sep 18, 2020 at 13:49
Some additional context is required to provide guidance, which is why I did not provide a complete answer. In the strictest of sense, there is no breaking change between v1 and v2 as you've described. Both versions have the customerid and both are of type string. However, if one or more clients are making an assumption about it being an email address, it may be a problem. That is a judgement call. It would be no different than if customerid were a GUID. In the strictest sense, the contract can only specify that it's a string. — Chris Martinez
– Chris Martinez, Commented Oct 6, 2020 at 18:51

Rajdeep D · Accepted Answer · 2020-09-10 17:13:17Z

1

You can achieve this by creating a AcceptHeaderAttribute and pass Accept:[attrbute value]

Like, in the below code, I create an AcceptHeaderAttribute

[AttributeUsage(AttributeTargets.Method)]
    public class AcceptHeaderAttribute : Attribute, IActionConstraint
    {
        private readonly string _acceptHeader;
        public AcceptHeaderAttribute(string acceptHeader)
        {
            _acceptHeader = acceptHeader;
        }
        public int Order { get; set; }

        public bool Accept(ActionConstraintContext context)
        {
            return context.RouteContext.HttpContext.Request.Headers["Accept"].Any(x => x.IndexOf(_acceptHeader) >= 0);
        }
    }

And here is the use,

[HttpGet]
        public User GetUserName()
        {
            return new User { Name = "Abcd" };
        }

        [HttpGet]
        [AcceptHeader("app/vnd.user")]
        public User GetUserEmail()
        {
            return new User { Name = "[email protected]" };
        }

And here is fiddler response

answered Sep 10, 2020 at 17:13

Rajdeep D

3,9201 gold badge12 silver badges18 bronze badges

Sign up to request clarification or add additional context in comments.

7 Comments

191180rk Over a year ago

Going by this reference developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept . Accept header are meant to specify MIME types like text/html, application/xhtml+xml etc. Arent we violating principle here with above example? BTW app/vnd.user is random value or its by some standard/convention?

Rajdeep D Over a year ago

vnd is for vendor. it should be application/vnd.newuser. To save time I wrote app/vnd.user. Please check thi Article: jacobbednarz.com/posts/…

191180rk Over a year ago

Reading your article clears up few things. But still is there any reason you have preferred "Accept" header to do this validation rather than introducing custom header starts with "X-" ? Also for any reason "Accept" header approach better then appending queryparameter?

Rajdeep D Over a year ago

You scenario is like API versioning. API versioning can be done by query param, custom request header, url, accept header. When use query param to target a specific api version, confusion arises in longer term as Query param will never tell you which version of the api you are targeting and you may required to inspect api code. Now the end goal is not to break existing client. So once you introduce custom header, change to the header is not very easy. Like if you introduce, x-new-user, in next version you cannot make it x-first-user as this will break existing clients.

Rajdeep D Over a year ago

You will be creating a tight coupling with custom header key. With url api versioning, existing clients also need to start using new url structure if they are using non-versioning one. Whereas Acept header is the easiest to change in longer term, reduced testing effort.

|

Collectives™ on Stack Overflow

How to introduce change in web api response payload structure without breaking existing integration

1 Answer 1

7 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

7 Comments

Your Answer

Sign up or log in

Post as a guest

Related