How far should I validate user input in my own created API?

Question

I got something here that bogs my mind a bit.

Let's say I write me this API (in TS), check out some of these properties:

export class MyAPI{
        propertyThatShouldContainSuffix:Array<string>; // like .jpg or .mp3 
        somethingElses:Array<SomethingElse>; //instances of some class
        enumProperty:SomeEnum; // enum SomeEnum{a,b,c,d}
        constructor(object){
           /*
             this object is input by the API consumer,
             and its properties will be assigned to the new fields of
             the new instance
                              */
        }
     }

Valid usage example:

var myApi = new MyAPI({
   propertyThatShouldContainSuffix : ["img.jpg","video.mp4" ...],
   somethingElses : [new SomethingElse(/*yada yada*/),new SomethingElse(/* whateverrr*/) ...],
   enumProperty:2
});

Input that may cause problems:

var myApi = new MyAPI({
       propertyThatShouldContainSuffix : ["img","video",5 ...],
       somethingElses : [new SomethingElse(/*yada yada*/),new SomethingTotallyElse(/* whateverrr*/) ...],
       enumProperty:6
    });

As you can see, the first property is an array of strings that need to have a suffix, like an image, that should be .jpg or .png or whatever. There is an array of objects that should contain some fields, and finally an enum field, let's say that it ranges from 0 to 3.

Now, it all works fine and stuff when you input the expected values into it (e.g all strings in first array has the right suffix and so on).

But then I thought that I should handle bad input, like a user that will send all his image names without any suffix, or will give me a "9" as input for the enum, send objects instead of arrays, and so on.

BUT! and here's the problem: how far should I go with this? should I check that every property is correct(e.g what is supposed to be an array is really an array, that all "supposed to be suffixed" are suffixed, that all "somethingelses" contain all correct fields?

Because if I do, this is a whole mess of overhead on every creation of an instance of MyAPI object.

Or should I only do something real basic like check if he didn't misspell some field in the object(therefore exposing helpless users to the perils of "but why isn't this working? stupid stupid API!") ?

Or anything inbetween?

Answer 1

You should provide an API with documentation. In your documentation you should document what unusal inputs are handled well, what incorrect inputs you will detect and how you will respond to them - and what incorrect inputs you will not detect. And your implementation should follow that documentation.

Your API can be written with the attitude "calling it the wrong way is a programming error; so you need to fix that error". That's perfectly fine. So when I say "what incorrect inputs you will detect and how you will respond to them" - saying that you will definitely crash is absolutely fine with me. And if you say that you don't check for some incorrect input, that means passing that incorrect input is a bad programming error that might lead to hard to find bugs. In that case, well, the users of your library need to read the documentation.

Answer 2

Checking the file suffix seems easy, but ultimately pointless. A file named foo.bar might be a valid jpeg file. A file named reallyIsA.jpg might be a nasty virus.

Remember when some corporate firewalls forbid you from emailing .exe or .zip files and everybody just changed the extensions?

IMO, your API should specify "a file in one of these image formats: (put list here).". Then specify the exception or reply if it is not one of those.

Answer 3

In this example and in most other real world examples the overhead of validation will be negligible compared to the work your API is supposed to do. For starters you may want to create a class MediaFile that encapsulates the input of your API. All validation can then be done in the constructor of the media file class. MediaFile could be abstract and you could have descendants JpgFile and Mp3File. Or you could have a generic MediaFile class that takes a file path and figures out the type of the file. If your MediaFile class finds an issue with the specified file you can make it blow up with a clear message. That would clean things up and your API would be sure to receive valid, fully initialized MediaFile objects. Checking for null would be sufficient.

What doesn't feel right for you now is that you are pushing too much non-core responsibilities into your API. Those can all be handled upfront, external to the API.