REST JSON API optional parameters design

Question

Our goal is to develop API where you can POST /data/save/ that will accept some JSON data like below. The main requirement that JSON should contain one of the following attributes: "attribute1", "attribute2", "attribute3". Namely when one attribute is exist another one should not exist.

{
   "name": "test name",
   "attribute1": [
       "test1", "test2"
    ]
    or
    "attribute2": [
        "test3", "test4"
     ]
     or
     "attribute3": true
}

The question is how to correctly design such API that it will be easy to use and not confused from the client side.

It would be good to know some best practices in such direction.

score 1 · Accepted Answer · answered Dec 29 '15 at 12:28

1

I would return a

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

and a phrase explaining that multiple attributes are not supported.

answered Dec 29 '15 at 12:28

sschrass

7,014
6
43
62

Thank you! I guess it would be the best option for our case in order to support optional attributes. Because it would be easier to support one endpoint with validation instead of few endpoints. – fashuser Dec 30 '15 at 13:38

score 1 · Answer 2 · edited Dec 29 '15 at 12:38

1

I agree such API is confusing for client side.

What's about creating different endpoints:

POST /data/save/attribute1 json_1

POST /data/save/attribute2 json_2

edited Dec 29 '15 at 12:38

Milap

6,915
8
26
46

answered Dec 29 '15 at 12:36

Anatoly Deyneka

1,238
8
13

score 0 · Answer 3 · edited May 23 '17 at 12:04

0

A custom media type should clarify how to use your API. It should specify what to include in your request.

Another solution might be, building the request like this:

{
   "name": "test name",
   "attr-key": "my-attribute1",
   "values": ["test1", "test2"]
}

edited May 23 '17 at 12:04

Community

1
1

answered Dec 29 '15 at 14:20

Ralph Müller

1

introducing mediatypes is discouraged. – sschrass Dec 29 '15 at 15:28

REST JSON API optional parameters design

3 Answers3