Strict APIs vs. Forgiving APIs

https://publicobject.com/2008/06/strict-vs-forgiving-apis.html

by ajabhish • 6 years ago

54 47 6 years ago

publicobject.com

ajabhish• 6 years ago

What is preferred by API consumers?

CharlesW2• 6 years ago

The author's opinion in TFA is "strict". That's my preference as well, for the same reasons they state.

dicroce• 6 years ago

If I had to choose I'd say prefer strict... But reading this made me wonder: what if you could be strict during development but switch to forgiving for deployment?

Vinnl• 6 years ago

That sounds like the modern JavaScript toolchain. During development, run a linter to make sure you're not using error-prone or outdated functionality, run a type checker to make sure you're passing sane data around, but when running in the browser, don't blow up in the user's face.

avianlyric• 6 years ago

what if you could be strict during development but switch to forgiving for deployment?

That sounds like a debugging nightmare, where your production system is subtlety different in behaviour to your dev system.

Also how do you know that the forgiving behaviour is correct in production? Maybe it prevents a couple of scary error messages, but it could just as equally allow incorrect inputs to be processed and stored, creating a data cleanup nightmare later.

gpderetta• 6 years ago

that's the idea behind assert in C/C++.

4thwaywastrel• 6 years ago

This is what we do, but we warn rather than just swallow it. I find it the best of both.

CharlesW2• 6 years ago

It seems like "forgiving with warnings" should be another option listed here. This also lets API creators do neat things like warn people ahead of time of future deprecations, etc.

megous2• 6 years ago

Something I read in the RFC for email message format (or maybe elsewhere, but I have it associated with email for some reason) is: to be strict in output that you produce, and lenient in the input you accept.

I think it makes some sense for data formats, if you want max compatibility of independently developed software that processes the data. Not sure about APIs though. Having them fail fast on unexpected input is pretty valuable.

showerst• 6 years ago

I used to be a big fan of 'strict send, lenient accept', but looking at systems built on it -- (html, email), I think being lenient around format deviation just turns everything into a big mess.

Granted those are two of the most successful technologies ever, so perhaps it was the right call =).

megous2• 6 years ago

But html and email are also incredibly successful... so hmm?

tynorf• 6 years ago

I believe being lenient in accepting input is what leads to SSRF attacks (HTTP request smuggling via disagreeing `transfer-encoding` and `content-length` headers).

chrismorgan2• 6 years ago

That’s Postel’s robustness principle. Many people now believe it was a harmful idea that actually achieves the opposite of what it was intended to achieve. https://tools.ietf.org/html/draft-iab-protocol-maintenance-0... expounds. (I confess I rather liked the earlier name of the draft, postel-was-wrong.)

greggman3• 6 years ago

Plenty of people have also argued that being strict on input would be bad

https://web.archive.org/web/20060613193727/http://diveintoma...

https://friendlybit.com/html/why-xhtml-is-a-bad-idea/

Joker_vD4• 6 years ago

I think that's a trick question. If "substring()" has "substring(int start, int end)" semantics, then I prefer the strict version: it must be 0 <= start < len(s), start <= end <= len(s), otherwise it'll throw an exception.

But if the semantics is "substring(int start, int length)", then I prefer the partial forgiveness for the length parameter: if start + length > len(s), then assume length was actually len(s) - start; but if length < 0, still throw an exception.

gruez• 6 years ago

Why should the out of bounds behavior be different depending on the semantics of the second parameter?

masklinn• 6 years ago

Because if you want to slice to the end you can just ask for the source's length which is free in most languages (it's not in C or in list-based languages), whereas the "result length" version is either going to have to be computed from the collection length or it's a constraint. In the latter case especially it's annoying to have to do weird computations on the basis of length in order to clamp your existing constraint in case the result would already fit.

misterdata2• 6 years ago

Only if the stricter one really requires you to use it differently (e.g. because of checked exceptions). If not you will have to guess for each function if it is strict or not, which potentially causes even more trouble if you get it wrong.

Joker_vD4• 6 years ago

Well, that's one of the reasons why I sometimes myself writing unit tests for the 3rd-party library functions: did I read the docs right? What about some obvious yet still undocumented edge cases? With particularly convoluted APIs those tests sometimes actually end staying in the project's tree.

misterdata2• 6 years ago

Having used both stricter (Rust) and more loose programming languages (JS), I can add that stricter APIs have made me think more about edge cases than the less-strict APIs. In the less-strict languages I often find myself debugging some edge case, whereas in the stricter languages I am more often required to think about edge cases up front (including those that I know will not be relevant, so in some cases this causes more work than necessary!). Still I much prefer the stricter APIs.

kstenerud• 6 years ago

Suppose it's the early 1990's and you're James Gosling implementing String.substring(int, int) for the first time. What should happen when the index arguments are out-of-range? Should these tests pass? Or throw?

It depends entirely on what the rules of the API are. Function signatures in most languages lack any form of compiler enforcement of rules, so you must implement them in code, and then list the rules in the function's description. The strictness you apply doesn't matter as much as your description of what argument range is allowed, and how the behaviour is affected.

For example, substring could allow overshoot with the description "If the substring would go beyond the end of the string, the remainder of the string is returned".

What you should be concentrating on is the 80% use case of your API. What will 80% of your users need? If the lack of length overshoot support would be cumbersome to the 80%, you support overshoot. If it's useless to the 80%, you leave it out. You can also implement things as layered APIs, with more general lower level functions, and then higher level functions that are more strict. Then the 20% can use the lower level functions for their esoteric use cases, and the 80% can stick to your easy-to-use and hard-to-screw-up high level API.

Karellen• 6 years ago

I like Rusty Russell's classic "Hard to Misuse Interface Levels". The first couple of items are

0: Impossible to get wrong/DWIM

1: Compiler/linker won't let you get it wrong

...through

9: Read the correct LKML thread and you'll get it right - SET_MODULE_OWNER

...all the way up to 17. I'll let you discover the rest yourself :-)

https://ozlabs.org/~rusty/ols-2003-keynote/img39.html

an_d_rew• 6 years ago

pure gold

madmax108• 6 years ago

As someone who writes APIs for a living, this is often something interesting that I find a lot of division on:

Say you have an API that is documented to accept params A,B or C i.e /v1/api?A=1&B=2&C=3

What should happen if you pass a param D to it? i.e. /v1/api?A=1&B=2&C=3&D=4

The two most common schools of thought are:

1) Ignore D

2) Throw an error

Both present their own problems, esp. when D may be closely related to A,B,C. Interesting how API design also tends to side with personal preferences for strictness or leniency

rvnx• 6 years ago

In second case you may break other people's software because of your expectations on how the world should work.

For example, Twitter pages not working if there is a fbclid parameter.

selfhoster11• 6 years ago

FBCLID and UTM tags are their own kind of craziness. They shouldn't have been present in the first place.

taylodl• 6 years ago

What's the old adage - be lenient in what you accept, be strict in what you produce? That ensures you can operate in a wide variety of scenarios with little to no interaction and coordination with the clients.

jcranmer• 6 years ago

What if D is "always-use-utf8"? Or, in general, the option being requested is something that places much more stringent restrictions on semantics.

There are two main reasons that users might validly use unknown options. The first is that it's an option with valid semantics in different versions/implementations of the protocol. The other is that you're reusing an option block for many API calls, and some of the options may not be relevant for some of those APIs. For the first use case, erroring out (or at least warning) is usually the superior solution: you don't know what it means, so you can't guarantee that you'll implement it correctly. For the latter use case, ignoring can be a safe solution.

FWIW, there's been a pushback against Postel's Law (which is what the adage you cite is usually called) in more recent times. In particular, it should be emphasized that the law is generally most applicable when you're dealing with multiple interpretations of an ambiguous specification, and is least applicable when the standards are prescribing or proscribing particular behavior.

wvenable• 6 years ago

The strict vs. lenient in this case also comes down to extensibility. HTML for example is notoriously forgiving and HTML parsers are quite complex because of it but it allowed HTML to be extended and improved upon while maintaining backwards compatibility.

If the first web browser was extremely strict on the tags and structure it supported then web could not have evolved that way that it did.

aimor• 6 years ago

In my experience forgiving APIs don't play well together. I've inadvertently tried it and wind up having to make everything 'forgiving in the same way'. Otherwise out-of-range inputs mean different things to different functions, and using multiple APIs requires tracking all the forgiving behavior.

z3t4• 6 years ago

Its not always binary. You want to throw an error at even the slight amount of error. This will annoy users, but over time as bugs and edge cases are fixed - it will lead to a very robust program.

Meanwhile you want to save time/work for the caller. You dont want the caller to need many lines of boilerplate just to setup the call.

RocketSyntax• 6 years ago

if it accepts a list of items [], but only a single string is provided "", accept it

thamer• 6 years ago

For reference, this is what String.substring(int, int) does[1] in Java:

    public String substring(int beginIndex, int endIndex) {
        int length = length();
        checkBoundsBeginEnd(beginIndex, endIndex, length);
        ...

Where checkBoundsBeginEnd[2] does:

    static void checkBoundsBeginEnd(int begin, int end, int length) {
        if (begin < 0 || begin > end || end > length) {
            throw new StringIndexOutOfBoundsException(
                "begin " + begin + ", end " + end + ", length " + length);
        }
    }

(as it should, in my opinion).

[1] https://github.com/AdoptOpenJDK/openjdk-jdk11/blob/f0ef2826d...

[2] https://github.com/AdoptOpenJDK/openjdk-jdk11/blob/f0ef2826d...

postalrat3• 6 years ago

This may be unrelated but every time I see a timestamp as a string in json I wonder why. There is so much less to go wrong with a numeric unix timestamp yet 9 times out of 10 a developer will use a string.

If you are going to make things strict at least make it hard to mess up.

genidoi• 6 years ago

Unix timestamps aren't human readable

m4632• 6 years ago

most logfiles beg to differ. (bleh!)

they're also... unix ... timestamps.

postalrat3• 6 years ago

Use better tools.

remus• 6 years ago

2038 called, they'd like to talk.

postalrat3• 6 years ago

Javascript numbers (as in JSON) can safely represent integers much higher than a 32 bit integer.

bartvk• 6 years ago

An ISO date with timezone can be useful, if you would like to know the timezone when a particular bit of data was recorded.

crote• 6 years ago

If you mean ISO 8601 and its "2007-04-05T12:30-02:00" timezone thingy, not really.

It doesn't store a timezone, but a UTC offset. Which is a problem because the UTC offset of a timezone may change.

This happens rarely enough that people do indeed use "ISO 8601 + offset" to store "timezoned" timestamps, but often enough that it'll probably end up corrupting your data sooner or later.

shhsshs• 6 years ago

My 2 cents... For the vast majority of the world where legacy (or at least not-programmed-using-super-modern-standards) systems are still in play, clarity is the most important factor in software. What happens when a legacy system is actually returning the number of seconds since epoch versus milliseconds? What if they're returning ticks (looking at you .NET...) because nobody realized ticks are inconsistent across different systems at the time the system was written?

I don't think you can get any more clear than an ISO timestamp (WITH time zone). Unix timestamps are great and efficient, but I personally value the absolute clarity of ISO above all else.

m4632• 6 years ago

obligatory link to postels law[1] and criticism

https://en.wikipedia.org/wiki/Robustness_principle

Strict APIs vs. Forgiving APIs

Related Stories