This API is a RESTful API, and as such will often provide extra contextual information along with data that is requested from the API. For example, if the API receives a request for information about a certain person, then the API will respond with the basic information about the name (e.g. first-, middle-, and last-name components, date-of-birth, etc.) as would be expected. The response will also include links that can be used to get more information specific to that name, such as Insurance Policies, Investment Accounts, Notes, etc.
The basic idea is to provide context, aka state, while maintaining a stateless interaction between the consumer and the API. The HATEOAS (Hypermedia As The Engine Of Application State) concept uses hypermedia (links) to accomplish this, thus the contextual information is delivered as links included in the response along with the result of the request.
There are emerging, competing standards for expressing HATEOAS links in JSON. This API uses HAL (Hypertext Application Language).
Practically, this means that the JSON representations of individual models, or lists of models, will have standardized tags that include links for related data.
All responses (other than errors) will include JSON property named _links which contains links to other resources related to the requested resource. The _links property will always contain at least one link named self (which contains a link get the requested resource again). Some responses will also include a JSON property named _embedded which can contain multiple JSON objects representing resources. Each of these objects, in turn, contains it's own _links and _embedded properties.
Responses containing one specific resource will not usually have an _embedded property.
Example: JSON+HAL representing a single resource (a Name in this case)
{
"ID": "9ba52df8-7159-4d82-9c53-45219c1477d0",
"FirstName": "Amuro",
"LastName": "Ray",
"Gender": "Male",
"PrimaryNameType": "Client",
"DateOfBirth": "1963-11-04",
"_links": {
"self": {
"href": "/v1/Names/9ba52df8-7159-4d82-9c53-45219c1477d0",
"title": "Amuro Ray"
},
"Notes": {
"href": "/v1/TopicNotes/?NameID=9ba52df8-7159-4d82-9c53-45219c1477d0",
"title": "Notes for Amuro Ray"
},
"Calendar Events": {
"href": "/v1/CalendarEvents/?NameID=9ba52df8-7159-4d82-9c53-45219c1477d0",
"title": "Calendar Events for Amuro Ray"
}
}
}
Responses containing a set of resources will always have those resources contained within the _embedded property of the top-level JSON. In these cases the _links property of the top-level JSON will contain one link for each of the resources found in the _embedded property (similar to a table-of-contents).
Example: JSON+HAL representing a list of resources (a list of Names in this case)
{
"_count": 2,
"_page": 1,
"_pagesize": 100,
"_links": {
"self": {
"href": "/v1/Names/?PrimaryNameType=Client",
"title": "Clients"
},
"names": [
{
"href": "/v1/Names/9ba52df8-7159-4d82-9c53-45219c1477d0",
"title": "Amuro Ray"
},
{
"href": "/v1/Names/02cff32e-a193-4775-afaa-563bbcca5dfb",
"title": "Casval Rem Deikun"
}
]
},
"_embedded": {
"names": [
{
"ID": "9ba52df8-7159-4d82-9c53-45219c1477d0",
"FirstName": "Amuro",
"LastName": "Ray",
"Gender": "Male",
"PrimaryNameType": "Client",
"DateOfBirth": "1963-11-04",
"_links": {
"self": {
"href": "/v1/Names/9ba52df8-7159-4d82-9c53-45219c1477d0",
"title": "Amuro Ray"
},
"Notes": {
"href": "/v1/TopicNotes/?NameID=9ba52df8-7159-4d82-9c53-45219c1477d0",
"title": "Notes for Amuro Ray"
},
"Calendar Events": {
"href": "/v1/CalendarEvents/?NameID=9ba52df8-7159-4d82-9c53-45219c1477d0",
"title": "Calendar Events for Amuro Ray"
}
}
},
{
"ID": "02cff32e-a193-4775-afaa-563bbcca5dfb",
"FirstName": "Casval",
"MiddleName": "Rem",
"LastName": "Deikun",
"Gender": "Male",
"PrimaryNameType": "Client",
"DateOfBirth": "1959-11-17",
"_links": {
"self": {
"href": "/v1/Names/02cff32e-a193-4775-afaa-563bbcca5dfb",
"title": "Casval Rem Deikun"
},
"Notes": {
"href": "/v1/TopicNotes/?NameID=02cff32e-a193-4775-afaa-563bbcca5dfb",
"title": "Notes for Casval Rem Deikun"
},
"Calendar Events": {
"href": "/v1/CalendarEvents/?NameID=02cff32e-a193-4775-afaa-563bbcca5dfb",
"title": "Calendar Events for Casval Rem Deikun"
}
}
}
]
}
}
For more information about these concepts, see:
Many of the properties of the models used in this API are 'Code' properties, meaning that the values that can appear in these properties are driven by pick-lists, and sometimes limited to a fixed set of possible values.
One example of this is the PrimaryNameType property of the Name model. This indicates that the specified Name is a Client, Prospect, Employee, Vendor, or other value. Other examples are Address Location (e.g. Home, Business, Mailing) and Investment Account Type (IRA, 401k).
Users of the Advisors Assistant applications see these choices as pick-lists when entering data. In many cases the API will automatically update the internal choice lists automatically (e.g. adding a new NameType code automatically as needed in response to a PUT or POST request). Certain Code Types do not allow new values to be added and require that models that are sent to the server conform to the pre-existing list of possible values. See the Reference for each of the models and their properties to see which properties are Code properties, and details for how each one can be interacted with. The lists can be manipulated directly via the "Codes" and "CodeTypes" endpoints.
Many endpoints in this API are capable of returning multiple resources in a list (e.g. returning all Names with the last name "Smith"). Paging is used to reduce wait time, server load, and bandwidth usage.
The following tags are included When a list of resources is returned from the API: _count, _page, and _pagesize. The _count property indicates how many resources are in the result. The _page property indicates which page of results was included (1 = first page, 2 = second page, etc.). The _pagesize property indicates how many resources are included in each page. Most endpoints of the API use 100 as the default _pagesize value, although a lower value can be specified by including an "pagesize" parameter in the query string. Some endpoints may have a different default and maximum page sizes, and will be noted in the documentation for each endpoint.
If a given list has the _count property equal to the _pagesize property, then it is highly likely that there are more results in the database than were included in the result. Additional resources can be returned by specifying a page number in the request query string (e.g. "page=3").
The API supports partial-model-updates - PUT requests to update an existing record where the JSON representing the resource is incomplete (passing only those properties who's values need to be updated). One example would be updating a Name's Date Of Birth without regard to any other properties on the Name resource. The following JSON can be submitted as part of the PUT request to the Names endpoint; passing the Name's ID in the URI as per standard REST practice (~/v1/Names/00000000-0000-0000-0000-000000000000):
{
"DateOfBirth": "1963-11-04"
}
In this example the Name's Date Of Birth would be updated while not changing any other properties about the name.