Trongate Docs
switch to dark modeswitch to dark mode
»
»
Querying Endpoints

Querying Endpoints

The Trongate API Explorer gives developers an opportunity to easily query Trongate's built-in API endpoints.  Let's have a some examples of different types of query in action.

Simple Get Where

Suppose you'd like to query a 'Get' endpoint by returning records where 'id' equals the value of '2'.  Using the API Explorer, we could create a simple JSON object that represents the conditions of our query and add our conditions into the 'parameters' textarea.  For example:

fetching where 'id' equals 2

The example above would produce an SQL query with the code:

SELECT * from fish WHERE id = 2

Multiple Conditions

Let's assume you'd like to query a 'Get' endpoint by returning records where 'id' equals the value of '1' and 'type' has a value of 'Mackerel'.  Using the API Explorer, we could achieve this by simply adding a additional parameter onto our JSON object. For example:

​{
​  "id": 4,
​  "type": "Mackerel"
​}

The example above would produce an SQL query with the code:

SELECT * from fish WHERE id = 1 and type = 'Mackerel'

'Or' Conditions

To execute an 'or' condition, simply add 'OR ' onto the beginning of a target parameter's key.  For example,

{
  "id": 4,
  "OR type": "Mackerel"
}

This would produce the following SQL query:

​SELECT * from fish WHERE id = 1 OR type = 'Mackerel'

Does Not Equal

To return results where a key does not equal a given value, we would use the != operator.  For example,

{
  "type !=": "Trout"
}

This would produce the following SQL query:

SELECT * from fish WHERE type != 'Trout'

Greater Than

Executing a query with a greater than condition can be achieved by use of the (greater than) '>' operator.  For example:

{
  "id >": 1
}

This would produce the following SQL query:

SELECT * from fish WHERE id > 1

Less Than

Executing a query with a less than condition can be achieved by use of the (less than) '<' operator.  For example:

{
  "id <": 1
}

This would produce the following SQL query:

SELECT * from fish WHERE id < 1

Like Conditions

We can execute a query with a 'like' condition by ending the key of a target property with the word 'LIKE' (all in uppercase).  For example:

​{
​  "type LIKE": '%rout%'
​}

This would produce the following SQL query:

SELECT * from fish WHERE type LIKE '%rout%'

Just To Let You Know
It's also acceptable to have just one percent symbol on your property value.  For example,
​​{
​​  "type LIKE": 'Trout%'
​​}
​​

This is in-line with how ordinary SQL behaves.

Not Like Conditions

We can execute a query with a 'not like' condition by ending the key of a target property with the words 'NOT LIKE' (all in uppercase).  For example:

​{
​  "type NOT LIKE": '%rout%'
​}

This would produce the following SQL query:

SELECT * from fish WHERE type NOT LIKE '%rout%'

What About Real World Situations?

Submitting queries via the API Explorer is one thing.  However, in real life situations it's highly unlikely that your end users will have the luxury of having a handy pop-up window for creating JSON objects and submitting parameters.  So, the question is:

How does all of this work in the real world?

Here's your answer:

GET Requests

For HTTP GET requests, we would pass our parameters via the URL.  For example, if we went to your app base URL followed by:

api/get/fish?type%20LIKE=%25acker%25

-> then, this would produce the query:

SELECT * from fish where type LIKE '%acker%'

How Could We Possibly Know This?

If you take a look at the screenshot below, you'll see an example, from the API Explorer, where a query has been invoked - using the object submission method - and the API Explorer has helpfully provided us with the URL segments that would produce our required query.

screenshot

So, figuring out how to construct meaningful URLs that submit custom parameters for GET requests, is just a case of opening the API Explorer, running some tests and - from there - we can easily deduce the URL structures required for our use cases.

Other Request Types

Did You Know?
PHP treats PUT and DELETE requests the same as POST requests

For other types of HTTP requests such as POST requests, your goal would to post variables and have them picked up by the in-built endpoint.

There are different mechanisms for posting values to an HTTP endpoint.  We'll cover two common scenarios - (1) posting values with ordinary JavaScript and also (2) posting values using Postman, which is a popular software application.

Posting Parameters With Vanilla JavaScript

To post parameters to an HTTP endpoint by means of, for example, a POST request - ordinary JavaScript requires that we:

  • build a JavaScript object that contains all of the parameters that we'd like to post
  • convert our JavaScript object into a JSON string
  • pass our JSON string into the request, as an argument

Vanilla JavaScript Example: 

//add your own targetUrl here
let targetUrl = 'https://example.com/api/get/fish';

let params = {
    id: 1,
    type: 'Mackerel'
}

var http = new XMLHttpRequest()
http.open('POST', targetUrl)
http.setRequestHeader('Content-type', 'application/json')
http.send(JSON.stringify(params))
http.onload = function() {
    // Do something with response, for example...
    console.log('the HTTP response status code is ' + http.status);
    console.log('the response body is ' + http.responseText);
}

Posting Parameters With Postman

Postman is a popular software package that some developers use to test API endpoints.  The screenshot below shows an example of Postman being used to execute a POST request and in doing so, parameters of 'id' and 'type' are sent as part of the request.

an example of a POST request in Postman

Key Points

  • For the 'body' section of our request, 'raw' was selected
  • A JSON object was then typed into the 'body' section of the user interface
  • At the 'response' section, 'JSON' was selected for the response body.  This was not essential but it means that our results are displayed in a nice, easy to read format
  • Postman helpfully displays the HTTP response code as well as the page load time.  It's near the bottom right hand side of the screen 





HELP & SUPPORT

If you have a question or a comment relating to anything you've see here, please goto the Help Bar.

 
×