Ross Summerell

Posted on Aug 31, 2018

Best Practice / Standard for API calls

#help

Good day all,

I've been brain storming an issue I have and thought maybe someone could point out the best practice for my situation.

I have build a .Net Core 2 Restful API. Its still being pieced together but I am running into a 'issue' which I am not sure of which is the best solution.

When calling my https://apiURL.com/AddressBook

I then can sent through an array of parameters from

PageSize
PageNumber
SearchFor & SearchBy ( these go hand in hand as its the field to search by what value but will have a default )

EG: https://apiURL.com/AddressBook?pageNumber=1&Pagesize=500

I am extending this list

OrderBy

Filterfor & FilterBy

The problem is I don't know how to add these to the URL as well, as you can order by more then one column at once, as well as add multiple filters.

Would anyone have some suggestions?

Top comments (11)

rhymes • Aug 31 '18

You could do something like:

https://apiURL.com/AddressBook?pageNumber=1&Pagesize=500&OrderBy=Field1,Field2

On the server you split by the comma and use the field names.
You also probably need to represent ascending or descending order, maybe wit a Order=asc or Order=desc ?

One other thing: if it's a REST(ish) API you should at least represent the resource correctly. If this is used to retrieve and filter a list of address books, the URL should be plural, maybe something like:

/address-books?page=1&per_page=500&order_by=field1,field2&order=asc&filter_by=field3

Unfortunately there's not a single standard for pagination, filtering and sorting. Some paginate with "page" and "per_page", others with "limit", others with dates, others with something else. Same goes for filtering.

This seems an interesting summary on the topic: specs.openstack.org/openstack/api-...

Ross Summerell • Aug 31 '18

Sorry it is plural, my call isnt even addressbook I was just trying to simplify for example sake. I did over look the asc and desc thank you!

And yes comma separated was the idea I had to go with, just felt like it might not be the best! But ill take a look at that topic now.

Chris James • Aug 31 '18

Please dont do comma separated

The HTTP spec lets you do order_by=field1&order_by=field2. Most decent HTTP servers and clients will support this out of the box.

So your clients dont have to write special code to send multiple values and you dont need to do any parsing code yourself.

Avalander • Aug 31 '18

Wow, I didn't know you could do that! Will that respect the order the parameters were set, though?

Chris James • Aug 31 '18 • Edited

Yup (or at least it should!)

If you happen to have Go installed I've made an example

package main

import (
    "fmt"
    "net/http"
)

func AmazingAPI(response http.ResponseWriter, request *http.Request)  {
    foos := request.URL.Query()["foo"]
    fmt.Fprintf(response, "you foo'd me good %+v", foos)
}

func main() {
    handler := http.HandlerFunc(AmazingAPI)
    http.ListenAndServe(":8080", handler)
}

Hitting http://localhost:8080/?foo=1&foo=2&foo=3

Results in you foo'd me good [1 2 3]

David Wickes • Aug 31 '18

Worth noting there's nothing in the URI spec for query to require this behaviour (it doesn't even require key=value, just that query strings are 'usually of the form key=value').

But it's definitely more conventionally used the way that @quii is describing - see for instance this on SO.

rhymes • Aug 31 '18

@quii you're right! Better than using commas

Chris James • Aug 31 '18 • Edited

Yes it is a shame, but it is for sure the convention

Best thing to do is write a test for your server and see if the library behind it supports it. If your server supports it, you're all good and you'll hopefully make it easier for your clients

Ross Summerell • Sep 3 '18

As much as I like this, I don't think Core/Linq supports this

Ross Summerell • Sep 3 '18

Let me add more detail to that,

I am getting a list of Resource Parameters

FilterBy
OrderBy
etc

This is only taking in the first OrderBy parameter I send in the URL.

Avalander • Aug 31 '18

I'm not sure if it's a standard approach, but I would just add the fields to the order parameter separated by commas

https://my.api/cats?breeds=bengal,abyssinian,persian,siamese

View full discussion (11 comments)

DEV Community

Best Practice / Standard for API calls

Top comments (11)

Read next

Crafting Robust Applications Across AWS, On-Premises, and Data Centers: A Comprehensive Technical Guide

Preparing extensions for Joomla 6. CMSObject -> stdClass.

What developers really want

Why Global Standards of API Design Save Your Team Time