The API supports the $select operator which allows you to return custom objects from the API. Custom objects are slimmed down versions of the full subject-based models the API has used since its inception.
Custom objects are a way to greatly reduce the amount of properties returned from the API. By default, the API returns a full object which has all of the API-exposed properties related to the subject you are using.
For example, if you run a GET on events, you get an object representing an event that returns 200+ properties of that event. However, most people need less than 10 of those properties.
The benefits to using $select and custom objects are:
- Performance of each API call is approx. 25% faster.
- You get only what you need.
- If you don't need anything returned in POST/PUT operations, you can use the '$select=None'. This gives you an added performance boost of approximately 25% for those calls.
Use $select and Custom Objects
Getting a custom object is a simple change to your existing API queries.
Support has been added for the "$select" operator to help you define your custom object. Here are some examples using the Events subject:
GET: https://yourv20URL/api/v1/events/10?search=EventID eq 5708$select=Description,StartDate,EndDate
The result of the query is an object that looks like this:
[
{
"Organization": "10",
"EventID": 5708,
"StartDate": "2010-04-01T00:00:00",
"EndDate": "2010-04-04T00:00:00",
"Description": "Phantom Of The Opera"
}
]
Notice it also added two properties that were not requested, EventID and Organization. This is because the software always includes the primary keys of the subject within the object.
Other examples of API requests are as follows and yield the same results as above:
PUT: https://yourv20URL/api/v1/events/10/5708?select=Description,StartDate,EndDate
POST: https://yourv20URL/api/v1/events?select=Description,StartDate,EndDate
If you do not need an object returned from a PUT or POST, you can use the 'None' keyword as part of the $select operator. This increases performance on PUT/POST operations as the API does not have to do a secondary retrieve after the insert/update.
PUT: https://yourv20URL/api/v1/events/10/5708?select=None
User Defined Fields (UDFs) and Custom Objects
You can also select specific User Defined Fields from the subjects that support UDFs. You must know 3 things to do this:
- Issue Type
- Issue Class
- User Field to select (UserText01, UserNumber01, UserDateTime01, etc...)
Below is an example for getting the UserText01 field from an account where the Issue Type = 'C' and Issue Class = 'CK'
GET: https://yourv20URL/api/v1/accounts/10/12345678?select=C|CK|UserText01
You can retrieve User Defined Fields while searching by specifying which user fields you want in the Select parameter. Note that, due to performance, this is Opt-In per field to help lookup efficiency. Once you specify an active user field, it is returned as a parameter in your custom object.
For non-account user fields, the format is “[User field Type]|[User field property name]”
Example:
https://localhost/ebms/api/v1/Functions10?search=EventID eq '13082'$select=BU|UserDateTime02
For account user fields, the format is “[User field Class]|[User field Type]|[User field property name]”
Example:
https://localhost/ebms/api/v1/Accounts/10?search=AccountRep eq '0002410'$select=C|04|UserText01,LastName
SDK Usage
If you use the SDK, making custom responses is as simple as including an option with the desired properties. In the below example, the first property is a standard account property (Title), while the second is a User Defined Field. Click here for an example.
var properties = new List<string> { "Title", "C|CK|UserText01" };
var options = new Ungerboeck.Api.Models.Options.Subjects.Accounts { Select = properties };
return apiClient.Endpoints.Accounts.Update(body, options);
Comments
5 comments
Something that's caught me out, when implementing Select..
When I wasn't using it, my StartDate was including the function start Time, which was quite handy.
Whereas when Selecting the StartDate, it only includes the Date.
Not sure if this is intentional, and I can work around it by checking both StartDate and StartTime in my code. But thought I'd point it out anyway!
/api/v1/Functions/10?search= Usage eq 'SIG' and StartDate ge DateTime'2021-09-03' and StartDate lt DateTime'2021-09-04
Returns:
"StartDate":"2021-09-03T13:00:00"
/api/v1/Functions/10?search= Usage eq 'SIG' and StartDate ge DateTime'2021-09-03' and StartDate lt DateTime'2021-09-04'$select=StartDate
Returns
"StartDate":"2021-09-03T00:00:00"
Simon
1 upvotes
Hi Simon,
That's pretty interesting. There must be something in the retrieve that relies on both being there. I'll have the Functions team take a look.
Thanks,
Rudy
0 upvotes
Hi Rudy Scoggins
I am trying to use the $select=None option with the relationships endpoint (via the SDK):
And getting a response:
This isn't the end of the world... as I can simply use $select=MasterAccountCode instead, but it looks like a bug?
0 upvotes
Hey Lee,
Thanks for the heads up. This does indeed look buggy. I gave it a shot on 97 and it appears to be working. What version are you running this on?
Rudy
0 upvotes
This is on .96E
I'll try and retest if/when the client has their test environment upgraded- thanks for the prompt reply :)
0 upvotes
Please sign in to leave a comment.