# 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;

{% tabs %}
{% tab title="Example" %}

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

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "_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": "Developer"
        },
        "object": "account"
    },
    "name": {
        "first": "Phineas"
    }      
    "posts": []
}
```

{% endtab %}
{% endtabs %}

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

```javascript
// 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:

```javascript
// GET /patientfiles/550891732390ac1832f3317f/connections?paths[]=access

{
    "_id": "550891732390ac1832f3317f",
    "object": "patientfile",
    "connections": {
        "object": "list",
        "hasMore": "false",
        "data: [{
             "_id": "550b9a25c59c1ef032ab641c",
             "object": "connection",
             "access": 2            
         }]
     }         
}
```