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

Read full post

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