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;

$.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"		
	}
});

MDAPIParameters* parameters = [MDAPIParameterFactory parametersWithParameters:
                                   [MDAPIParameterFactory parametersWithExpandPaths:@[ kAccountKey ]],
                                   [MDAPIParameterFactory parametersWithIncludePaths:@[ kConnectionsKey ]],
                                   [MDAPIParameterFactory parametersWithLimitPaths:@[ kPostsKey, kAgeKey, [MDAPIPathFactory pathStringWithComponents:@[ kNameKey, kFirstNameKey ]]] ],
                                   nil];
  
[[MDAPIClient sharedClient]
     patientFileWithId:[MDObjectId objectIdWithString:@"550891732390ac1832f3317f"]
     parameters:parameters
     callback:^(MDPatientFile *patientFile, MDFault *fault)
     {
         if (fault)
         {
             // Fault handling
         }
     }];

{
    "_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": "patient@example.com"                
            }
        }
    ],
    "creator": {
        "_id": "4578616d706c652055736572",
        "name": {
            "first": "James"
        },
        "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:

// 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-crtical 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            
         }]
     }         
}