Property Selection

Search…
Property Selection
Selecting context response properties using the API is accomplished using paths, include and expand query arguments.
paths
string[]
An array of properties to which the response should be limited.
include
string[]
An array of properties marked as optional that should be included in the response.
expand
string[]
An array of expandable reference that should be expanded in the response.
You can specify any of the above query arguments multiple times. For example, if you need to expand multiple properties, you can do so with the following query string.
?expand[]=account&expand[]=c_customProperty1&expand[]=c_customProperty2
Examples
The example below shows:
A reference automatically expanded by selecting a path in the referenced context (creator.name.first).
A response limited to the paths specified by the paths[] query arguments.
An explicit reference expansion using expand[]=account.
An optional path included with include[]=connections.
An implicitly included optional path through the use of paths[]=posts;
Example
Response
$.ajax({
    url: "https://api.dev.medable.com/example/patientfiles/550891732390ac1832f3317f?expand[]=account&include[]=connections&paths[]=posts&paths[]=age&paths[]=name.first",
    type: "GET",
    contentType: "application/json; charset=UTF-8",
    dataType : "json",
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"      
    }
});
{
    "_id": "550891732390ac1832f3317f",
    "object": "patientfile",
    "account": {
        "_id": "550b82336390d9cc34fdd1f0",
        "access": 1,
        "name": {
            "first": "Phineas",
            "last": "Gage"
        },
        "object": "account",
        "roles": []
    },
    "age": 25,    
    "connections": [
        {
            "_id": "550b9a25c59c1ef032ab641c",
            "object": "connection",
            "access": 2,
            "context": {
                "_id": "550891732390ac1832f3317f",
                "object": "patientfile",
                "path": "/patientfiles/550891732390ac1832f3317f"
            },
            "created": "2015-03-20T03:55:17.000Z",
            "creator": {
                "_id": "4578616d706c652055736572",
                "object": "Account",
                "path": "/accounts/4578616d706c652055736572"
            },            
            "state": 1,
            "target": {
                "email": "[email protected]"                
            }
        }
    ],
    "creator": {
        "_id": "4578616d706c652055736572",
        "name": {
            "first": "Developer"
        },
        "object": "account"
    },
    "name": {
        "first": "Phineas"
    }      
    "posts": []
}
Another example would be to automatically expand into the account reference and limit the properties to first name of the referenced account. The account name may not be accessible to the caller, but the Patient File account property reference has an ACL that allows the name to be read by caller with a Connection to the patient file: 
Expand Account Reference
// GET /patientfiles/550891732390ac1832f3317f?paths[]=account.name.first
​
{
    "_id": "550891732390ac1832f3317f",
    "account": {
        "_id": "550b82336390d9cc34fdd1f0",
        "name": {
            "first": "Phineas"
        },
        "object": "account"
    },
    "object": "patientfile"
}
Limiting Response Properties
Clients can shrink responses by limiting the properties returned by an API request using the paths query argument. Sub paths
must be in dot syntax (eg. name.first) and must exist in the object definition.
Object responses always include the _id and object properties.
Selecting an optional property using paths automatically includes it.
Selecting a path in a reference is possible (eg creator.name.first), automatically expanding the referenced context.
Expanding References
References marked as expandable can be expanded into full objects. This can result in less API calls when the client
wants to access information in the referenced object.
Depending on the reference property definition, using expand[] may limit the resulting expansion to a set of paths, may grant greater context access than the caller would normally have or allow greater access to a set of properties.
For more information about configuration options, see the section about References.
Optional Properties
Some object properties are marked as optional. Typically, these are non-critical properties that would be expensive to include
in every set of responses. For example, the connections and posts properties of objects are optional so wouldn't be
included in the result of a call to GET /patientfiles. To retrieve properties marked as optional, use the include[]
query argument.
When using paths[], included optional properties will be part of the response.
List Property Selections
Properties that return a list of contexts, such as posts and connections can have selection arguments passed by prefixing
them with the property name. For example:
// GET /patientfiles/550891732390ac1832f3317f/connections?paths[]=access
​
{
    "_id": "550891732390ac1832f3317f",
    "object": "patientfile",
    "connections": {
        "object": "list",
        "hasMore": "false",
        "data: [{
             "_id": "550b9a25c59c1ef032ab641c",
             "object": "connection",
             "access": 2            
         }]
     }         
}
Query Operators
Property Access
Last modified 1yr ago
Copy link