1

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?

  • 3
    On the clientside, handle every invalid input that could happen by regular users making mistakes. On the serverside, handle every kind of unauthorized/invalid input. You can't possibly check for everything, so just make sure that no attacks are possible. Clientside validation is mostly a convenience thing for users, as it can always be disabled. – Hugo Zink Feb 5 '16 at 14:15
  • every invalid input? you mean like for every string that representing an image path, i should check if it has a suffix of jpg or png or tif or gif? and that every field in the "somethingElse" class is the right type? isn't that too much overhead? – Or Yaniv Feb 5 '16 at 14:20
  • 2
    that depends entirely on how problematic it would be if certain invalid inputs were not validated. If the worst case scenario is an error occurring and the script stops, you may not want to handle that specific error. – Hugo Zink Feb 5 '16 at 14:22
  • yeah, well, that's about it - this API should be able to serve both programmers and non-programmers who won't be able to debug their input. that's why i want to at least give them better indication for where they might have an error. most times yes, mistakes will just result in script break or unexpected output – Or Yaniv Feb 5 '16 at 14:29
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.

  • true enough, and I certainly am going to add that documentation. honestly, these are not the programmers that worry me, I've seen enough libraries to know that even google will let you crash if you don't follow instructions carefully(like in google maps). I'm more worried about the no-coders who may use it. But I do guess there is a limit to what can be done, so I just need to post my examples real easy and clear – Or Yaniv Feb 6 '16 at 16:56
1

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.

0

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.

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.