API / Customer APIs common features

Common attributes in result


When you are calling GET methods for different endpoints the result does always have these common attributes:
  • count: the number of pages in the response
  • csvUrl: URL from where you can download the data in csv format
  • itemsPerPage: how many data items is present on one page
  • excelUrl: URL from where you can download the data in excel format
  • next: URL to the next page of the responce
  • current: current page number in paged result
  • lastPage: last page's number in paged result
  • data: collection of items in question
  • previous: previous page's URL in paged result

Filtering results


If you don't specify any filters to GET methods, you will get all the items available from that specific endpoint. If you want to check if some specific data is present in the database or want to filter the results with some metadata, you can specify these filters in URL parameters. Notation for the parameters are:
<entity_name>.<metadata_field>=<value>
Here is a list of possible entities which you can use when filtering the results:
  • user
  • project
  • customer
  • allocation
  • projectrole
  • actual
  • projecttask
Metadata fields are the same which you can found from entities' GET responses. Here is an example of how you can filter with text fields. This would return all the users who's first name is Toni.
https://<your_environment>/customer-api/1.0/users/?user.first_name=toni

Special filtering parameters


You can filter the results of GET methods with parameters for example project.id=<id> or user.email=<users_email>. There is a number of special operators which you can also use.

__lte, __lt, __gte and __gt

For numeric values you can use these four comparisons:
  • __lte = Less or Equel than
  • __lt = Less than
  • __gte = Greater or Equal than
  • __gt = Greater than
These operators can be added to numeric values for example project.probability__gte=50 will filter out project's which probability is less than 50 percent.
You can use these operators for dates also.

Not equal, !=

For string values you can use not equal operator != for example project.code!= will leave out all the project's which code is not set.

__isnull

Some metadata fields in Silverbucket's database can be "empty". Then the value in database is null. You can filter with null values in Silverbucket's API with operator __isnull. For example user's external_id field can be set to null (empty) and it is possible to find all the entities which have empty external_id with this kind URL:
https://<your_environment>/customer-api/1.0/users/?user.external_id__isnull=true

__icontains

If you want to filter entities which have some specific string in some metadata field you can use __icontains operator. This will compare the given string to the metadata field and match will be made if the field contains the given string in any position of that data. For example if you filter with:
https://<your_environment>/customer-api/1.0/users/?user.first_name__icontains=ed
you might get results for persons whos first_name is like: Eddie, Freddie, Mohammed, etc.
How did we do with this article?