Http Api

Last Updated: 2023-10-29 02:01:34

As mentioned before, the fliddo API is varies in scale and starts with a simplest set of calls, however, this grows as new plugins are installed. The fliddo HTTP API documentation follows some rules and guidelines for understanding the URL endpoint definitions.

Let's go over the format used for the HTTP API documentation. First, we need to discuss inline variables which are values you can pass within the URL endpoint. This is not the same as variables passed to a endpoint using GET or POST. They are indented to bootstrap common elements of API programming such as retrieving data and lists.

URL variables are defined using brackets {variable} with an optional datatype or predefined list associated with it. The variable names are not important because you do not use them. They are listed to provide a rudimentary explanation/hint on intent. What is important is the position/placement of the variable within the URL.

Lets take a look at some exaggerated URL endpoints, their variable placement and potential values.

/accounts/{ id }
The first variable is considered to be an id with no format. This means you can pass an integer, alpha characters or combination of both. Remember, we are not using variable names, they are defined here as guidance on expected values. Valid calls to this endpoint would be /accounts/value or /accounts/1

/accounts/{ id:[digits] }
This is the same as the example above but with a datatype restriction. The restriction tells us that only digits are permitted as the value. Valid calls to this endpoint would be /accounts/1 or /accounts/8934756437473879

/accounts/{ var1:[alpha] }/{ sort:[asc|desc] }
This example uses multiple variable placements with restrictions and introduces predefined lists. A predefined list is a group of acceptable values that are not case sensitive. In this case, we are looking at a URL variable that controls the sort order of a list. Valid calls to this endpoint would be /accounts/value/asc or /accounts/othervalue/desc

/accounts/{ field:[alpha] }/{ sort:[asc|desc] }/{ show:[digits] }
The last example is similar to the previous but introduces another variables related to lists which is the page to return. Valid calls to this endpoint would be /accounts/value/desc/1 or /accounts/value/desc/2

Note: Inline variables are basic and limited to general selections. This allows us to select specific datasets through the use of an id or manipulate a list through the use of sorting and page selection.

We mentioned before that API endpoint variables are not the same as inline variables. Now that we understand inline variables, we can combine them with variables and use an API call.

Although there is no restriction, it's good practice to use POST instead of GET when submitting variables to an HTTP API endpoint. Lets take a look at one of the more basic examples, the concept if the same.

/accounts/{ id }

When using POST, it simplifies the process and allows you to pass variables as with any other submission URL. When using GET, there are two ways to pass data to the URL. One is the traditional way by adding a question mark followed by key/value pairs. The other is adopted from Seo standards which is to provide the key/value pairs as part of the URL path.

For example, valid calls to this endpoint would be /accounts/1?var1=1&var2=2&var3=3 or /accounts/1/var1/1/var2/2/var3/3

Ultimately, the choice is up to you but POST provides a cleaner approach.

Was this page helpful?