5

Suppose that the server restricts a JSON field to an enumerated set of values.

e.g. a POST request to /user expects an object with a field called gender that should only be "male", "female" or "n/a".

Should a wrapper library make sure that the field is set correctly before making the request?

2
  • when I assume you mean sex and not gender ISO 5218 provides for 4 possible vallues: "male","female","n/a","unknown". A lot of times data in databases isn't filled because it's simply unknown. I've ran into api's left and right which would not work well with unknown fields. Where I had to "make up" data just to get them to work. Which imo is bad.
    – Pieter B
    Oct 2, 2017 at 15:00
  • What will you do if the server changes to allow new field values?
    – Jack
    Oct 3, 2017 at 4:04

4 Answers 4

6

If you're dealing with a networked resource (like you implicitly are with a REST API), then it makes a lot of sense from the perspective of the user to do as much pre-validation as possible, to save the overhead of the network round-trip to their user experience.

Further, in some cases the API is going to be restricted on the # of requests you make, or charge you based on some volume. In both of those cases, it makes a lot of sense to pre-validate before sending.

So in general, I'd say yes, validate before sending whenever you know what the API will expect.

2
  • 1
    In addition to saving overhead, validating in the wrapper/client often makes it easier to return very specific errors (that is: many API's have terrible validation feedback), which is part of the added value that comes from using such a wrapper.. Oct 3, 2017 at 11:53
  • @JoryGeerts excellent point!
    – Paul
    Oct 3, 2017 at 12:53
3

IMO this depends mainly on one detail: Are you hosting the wrapper or it is just a client library?

To me in both cases seems that it will be up to you, if you are not doing any validation (against the wrapped API obviously, otherwise you MUST sanitize your inputs!) you can just come up with a convenient way of accessing said service, but there will not be much of a benefit, especially you are not adding too much on top, but just kinda extend the learning curve since people have to read your documentation instead of the official one, you have to think of compatibility with future versions of the API you are wrapping, etc.

If you are writing a client wrapping another client it seems that you can simply do some basic checks, but rely on the underlying implementation to know best how to handle stuff. If you are writing a hosted wrapper, you probably should have those checks in place and instead of acting as a simple proxy to the official, you can transparently provide compatibility - a.k.a bridge/compat layer - in which case it will be pretty good to have your checks in place.

Things can get convenient if the targeted API actually uses a schema (JSON-API, WSDL, XSL, JsonSchema, Swagger/OpenAPI and the likes) since you can get a dynamic validation without too much extra effort. There are many libraries which can handle parsing and validation for you, so you might not have to do all that much. BUT you absolutely have to if the API you are wrapping is poorly documented, does not give informative error codes (we all know 1 vendor that gives you "400 - Bad Request - Something unexpected happened")

2
  • Maybe I'm missing something here, but how does it extend the learning curve? The point is that validation happens under the hood. The developer would read in the API docs that the value provided must be one of the allowed values, and the burden falls on the maintainer of the library to make sure that validation complies to those rules. I agree that it does not provide much of a benefit, I was mostly curious about standard practice. Oct 2, 2017 at 14:42
  • @GuybrushThreepwood I was referring to the part where when using a wrapper you can't just search "How to do X with Y", but you have to look for the wrapper's docs that might support it or not be possible (depending on the wrapping) and one might need to also know the original API as to know what to look for in the new one Oct 3, 2017 at 12:56
1

When in doubt, try to remember how we do it on the web

Should a wrapper library make sure that the field is set correctly before making the request?

The web analog of this is an html form, that is going to post application/x-www-form-urlencoded data, where the representation of the form itself includes a description of an input control that supplies both a parameter name and a list of expected values.

The web browser would, in turn, produce a UI with visual elements that clearly illustrate the range of allowed values, and would construct the appropriate request body from the selection made by the human operator.

Technically, the range of choices doesn't need to be included in the representation; a media type that describes the range of allowed values will do. I think you'll find that designing support for change into your media type definitions will pay off in the long run.

Of course, not all user agents enforce the ranges described within the representations. curl, for instance, won't prevent a spelling error if you try to craft your own response.

There's no obligation that the wrapper library support describing requests with primitives. If you think introducing a Gender value type will increase adoption of the library or improve the experience of using it, then by all means you should do so. Tradeoffs - the happy path gets easier to use, the edge cases get harder.

0

Yes. Ideally it would be a compile time validation. So you would be unable to even write code that called the function with an incorrect type.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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