Custom search in an API

Question

I have an API with a custom search over half a dozen fields, something along the lines of the following, although may also include sensitive data as I use the same approach for the same type of search elsewhere

Username
Email
Firstname
Lastname
Department

I'm generally using a RESTful approach, so retrieving users would be something like the following for a list of users, or a single user

GET /user
GET /user/1

For the search, however, I'm slightly baffled as to how to allow this. My original intention was to use JSON in the request body, eg

{
    "username": "someuser",
    "department": "sales"
}

I can't use the request body as would seem logical (and as I use for POST etc actions), though, because it isn't supported by Chrome as far as I can tell (or at least, not by the PostMan addon, which we use for testing)

As such, what's the best way to perform this search?

The options I see

Use a header

Which seems like the "wrong" use of headers, but also the closest to the origial request body

Use parameters in the URL

eg

GET /user?username=someuser&department=sales

But that gets messy with the controller (using C# Web API), because I can't leave items blank. So the request would be more like this, unless I had a ton of overridden methods to handle the different permutations. This seems... messy

GET /user?username=someuser&email=&firstname=&lastname=&department=

Perhaps more importantly, it leaves a little too much visible "over the shoulder": this is within a healthcare setting, and while there are unavoidable times where things are displayed, I would rather keep this to a minimum (the data itself is, naturally, SSL encrypted during transmission)

Use a different HTTP verb

I could use POST or some other verb, which would work but is counter-intuitive and goes against both the RESTful approach (as far as I can tell) and my own standards within the project, so could be confusing.

Has anyone else run into this? What's the "official" or best way to handle it?

Thanks, although I've just added a further objection to the URL parameter option - this is in a healthcare setting, so items in the URL, particularly once they're not obviously visible in the form the user is filling in, isn't ideal. — Jon Story
– Jon Story, Commented Feb 18, 2016 at 17:07

Kenneth · Accepted Answer · 2016-02-18 17:11:28Z

1

There's no real "official" way. In this case, I would just bend the rules of REST a bit and just use a post, passing in a body is what POST-methods are for.

Regarding no support from Chrome: This is fully supported in Chrome as well as in the PostMan extension (you need to select a POST-method and choose the raw option for the body and then select JSON)

On the other hand, the querystring could also be a good option. You can have empty items by using default parameters in your controller:

public ActionResult Search(string userName = "", int departmentId = 0)
{
    ...
}

edited Feb 18, 2016 at 17:11

answered Feb 18, 2016 at 17:08

Kenneth

28.8k7 gold badges65 silver badges85 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Jon Story Over a year ago

Thanks, I may have to resort to bending the rules: you probably missed it as (from the timing of your post) I think I ninja-edited while you were writing your answer, but I have a further objection to putting search terms in the URL due to the setting the API is used

Kenneth Over a year ago

Yes, sorry, I missed that. If indeed the data is sensitive, then it's better not to use GET at all. Which makes the choice for POST even more obvious

Jon Story Over a year ago

With SSL and no parameters, I'm not aware of a significant difference between POST and GET, but yeah it's looking like the only real option. I'm assuming you instantly discounted the header entirely?

Kenneth Over a year ago

Yes, wouldn't do that

Collectives™ on Stack Overflow

Custom search in an API

1 Answer 1

4 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

4 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related