Reducing response size

By default Spaces returns all fields for an object when it is requested, including the related entities fields, this can result in larger than required responses, especially if you only require a few fields from a large object.

Every endpoint on Spaces supports field filtering, this allows you as a developer to specify what fields you wish to return.

This can be accessed on all endpoints by including the fields= query string or fields[users]= for included objects. The list of fields provided would then limit the response to only those fields.

Sample Comment Response

{
    "comment": {
        "commentId": 31,
        "parentCommentId": 0,
        "pageId": 1,
        "content": "Hi there",
        "createdBy": {
            "id": 1,
            "type": "users"
        },
        "createdAt": "2018-12-11T11:13:23.852Z",
        "updatedBy": {
            "id": 1,
            "type": "users"
        },
        "updatedAt": "2018-12-11T11:13:23.852Z"
    }
}

You can limit the fields returned using the fields query string .../v1/spaces/1/pages/1/comments/31.json?fields=commentID,content. As you can see, we only want to return the commentID and the content field in this case.

This becomes useful when data size is important, such as mobile clients, or even the website when being accessed by a user on a phone. The original response being 466 B size and the limited being 378 B. This would become especially useful on list endpoints.

Sample response with Comment Id and content only

{
    "comment": {
        "commentid": 31,
        "content": "Hi there"
    }
}

It can also be used to limit any related entities fields by providing fields[users]= in the querystring, with users being the entity name.

An example is shown, again with a comment response, but this time with the ?included=users query parameter:

Sample response with users data sideloaded

{
    "comment": {
        "commentId": 31,
        "parentCommentId": 0,
        "pageId": 1,
        "content": "Hi there",
        "createdBy": {
            "id": 1,
            "type": "users"
        },
        "createdAt": "2018-12-11T11:13:23.852Z",
        "updatedBy": {
            "id": 1,
            "type": "users"
        },
        "updatedAt": "2018-12-11T11:13:23.852Z"
    },
    "included": {
        "users": {
            "1": {
                "userId": 1,
                "firstname": "Test",
                "lastname": "User",
                "email": "test.user@test.com",
                "avatar": "https://localhost/test.jpg",
                "isAdmin": true,
                "state": "active"
            }
        }
    }
}

If limiting by comments and included users we send a url like this .../api/v1/spaces/1/pages/1/comments/31.json?include=users&fields=commentId,content&fields[users]=firstname,lastname.

So in this case, we want to receive only the commentId and content fields as before, but are also only interested in the firstname and lastname fields of the related entity.

Sample Response for limiting payload size

{
    "comment": {
        "commentid": 31,
        "content": "Hi there"
    },
    "included": {
        "users": {
            "1": {
                "firstname": "Test",
                "lastname": "User"
            }
        }
    }
}

Validation errors

All querystring properties are case insenstive and if a requested field doesn't exist or the related entity requested such as fields[users]=firstname doesn't exist a validation error is returned.

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.