DEV Community

Best Practice / Standard for API calls

Ross Summerell on August 31, 2018

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...
Collapse
 
rhymes profile image
rhymes

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-...

Collapse
 
rsummerell profile image
Ross Summerell

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.

Collapse
 
quii profile image
Chris James

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.

Thread Thread
 
avalander profile image
Avalander

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

Thread Thread
 
quii profile image
Chris James • 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]

Thread Thread
 
gypsydave5 profile image
David Wickes

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.

Thread Thread
 
rhymes profile image
rhymes

@quii you're right! Better than using commas

Thread Thread
 
quii profile image
Chris James • 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

Thread Thread
 
rsummerell profile image
Ross Summerell

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

Thread Thread
 
rsummerell profile image
Ross Summerell

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.

Collapse
 
avalander profile image
Avalander

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