Return errors or ignore unknown fields

[igtsvi]

Hello,

Out current pattern is to ignore all input fields which doesn't have any semantic meaning to the API. 

For example

Let's say to auth a user I need to specify fields: "username" and "password". The client POSTs to the API fields: "name" and "password" instead. The API will respond with an error that "username" field was not specified, but the fact that "name" field was specified in the request would be completely ignored. 

Question

Should the API also send an error stating that "name" was not a valid field? 

Our developer community is split on opinion whether an error or warning should be send back when an invalid field is included in the request or whether the API should only "react" to the fields it know what to do with.

A more complicated use case is when we up-version the API. If the latest version introduces a new field that changes behavior, the pattern is for the previous version to ignore the new field as if it doesn't exist.

Any best practices around this?

Thanks,

igtsvi

[Jørn Wildt]

I usually prefer to ignore additional unknown fields. 

At work we have an API that gets installed onsite on our customers servers. For this API we have an iOS app that interacts with the API (the app must obviously be configured with the URL) . This means that our server software must handle both newer clients talking to older APIs - and vice versa. In this case we have to be very relaxed about additional fields - and strive for 100% backwards compatibility in the API versions. So we only add new stuff - never make changes to existing stuff ... and ignore additional incoming stuff.

/Jørn

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[mca]

A good reference for this kind of question (reject or not) is known as Postel's Law[1] or the Robustness Principle.

created when TCP/IP was being formed, the Robustness principle acknowledges the reality that, if we all rejected any information packet that had at least one "bug" or unexpected element, we'd rarely complete a single data transfer. Instead, Postel says, we should "be liberal in what we accept" -- IOW, do the best we can to accept any offered input (as long as it is not harmful). This is usually realized with patterns like MUST IGNORE[2].

BTW - this approach is also they key to reducing the need for creating breaking changes in existing releases (and thus creating forked versions of a service, etc.). Clients that operate on the MUST IGNORE rule can usually consume messages "from the future" (new data and action descriptions in responses sent to "old apps" that don't understand/support these features) w/o breaking.

 

[1] https://en.wikipedia.org/wiki/Robustness_principle

[2] http://www.w3.org/History/19921103-hypertext/hypertext/WWW/MarkUp/MarkUp.html

mca

Mike Amundsen

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Andrew B]

+1 Mike for showcasing a new (to me) law! Adding to my repertoire, along with

Moore's law

Zawinski's law

Conway's law

Godwin's law

[igtsvi]

Thank you. This is very helpful.

igtsi

[sgoto]

+1 on ignoring.

f u cn rd ths u cn b a gd prgmr !