0

I am enhancing an existing API to provide shipping rates for a b2b web service. This specific endpoint returns a single rate based on matching request parameters such as the service level and package information to choose the best option. We currently support allowing the client pass in a carrier on the request, and it will then only select a rate from that carrier. However, in some cases the requested carrier does not offer a matching service, and the business has requested that we now allow this service to substitute the requested carrier for a different carrier that can satisfy the request, but only in certain circumstances.

I am planning to add a field to the request that allows the client to specify whether their requested carrier is absolutely required or just preferred, so that they know whether to expect an error or a substitution if that carrier cannot be used. However, I am not sure if this is the right way to do it, as it is not a common pattern, and I don't really know what to call such a field. Which of these options would seem most correct?

  1. A new field on the request which has an enum of [required, preferred] as possible values. What would this field be called?
  2. Two separate fields requiredCarrier and preferredCarrier in something like an OpenAPI oneOf so that only one of the two can be passed in from the client. This may require a new major version of the API.
  3. A structural change to the requested carrier field to make it an object with multiple properties, such as requestedCarrier: { carrier: 'FedEx', isRequired: true }. This would definitely require a new major version of the API.
2

I am planning to add a field to the request that allows the client to specify whether their requested carrier is absolutely required or just preferred, so that they know whether to expect an error or a substitution if that carrier cannot be used.

As a carrier that isn't required is implicitly preferred, tagging a carrier as preferred is unnecessary. All you need is a boolean field whether the carrier is required.

  • If the field is present and set to true, it is required.
  • If the field is present and set to false it isn't required, thus it is preferred.
  • If the field is missing, the default applies. The default is whatever the API does at the moment, thus the change is backward compatible.

How to name such a field? How about isRequired?

3
  • The biggest issue I have here is making sure the client would understand what isRequired does. The object with the carrier on it has several other fields such as serviceLevel, features, etc. That's why in my option #3 above, I put an isRequried field inside the carrier object, but that's a bigger change to the spec. – Aaron M. Eshbach Jan 11 at 22:08
  • 1
    @AaronM.Eshbach You can also name it carrierIsRequired and not put it into the carrier object. As for understanding, only the implementer needs to understand it, and usually that's what documentation is for. Trying to guess how an API works or what a property does by its name is a horrible idea. Don't ever do that! Programming is about knowing, not about guessing. As for "requiring major version", it doesn't since the field is optional. Existing clients continue to work as they used to if they just don't set this field at all, so it's a minor update (new feature). – Mecki Jan 11 at 22:14
  • @AaronM.Eshbach, Why is adding an optional field to the carrier object a bigger change than adding a similar field to the object containing the carrier object? – Bart van Ingen Schenau Jan 12 at 8:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.