Proper way to handle a large amount of relationship resources of a resource in JSON:API format (Content-Type application/vnd.api+json)

I'm building an api and I'm trying to handle the following problem:

The client sends the Accept header with application/vnd.api+json, so I reply with the resource in the JSON:API format.

Given are for example the following tables:

• Author
• Article

which have a 1:n-relation - so for example one author wrote 100 articles.

My goal is:

GET /author

returns the author (resource object) with a defined number of articles (relationship resource objects) - for example the first 3 articles he wrote.

In this format:

{
  "links": {
    "self": "http://example.com/author",
    "next": "http://example.com/author?page[offset]=2",
    "last": "http://example.com/author?page[offset]=10"
  },
  "data": [
    {
      "type": "author",
      "id": "1",
      "attributes": {
        "name": "Arthur"
      },
      "relationships": {
        "article": {
          "count": 100,
          "links": {
            "self": "http://example.com/author/1/relationships/article",
            "related": "http://example.com/author/1/article"
          },
          "data": [
            {
              "type": "article",
              "id": "4",
              "attributes": {
                "title": "1 reason why I should use json:api"
              },
              "links": {
                "self": "http://example.com/article/4"
              }
            },
            {
              "type": "article",
              "id": "7",
              "attributes": {
                "title": "2 reasons why I should use json:api"
              },
              "links": {
                "self": "http://example.com/article/7"
              }
            },
            {
              "type": "article",
              "id": "42",
              "attributes": {
                "title": "3 reasons why I should use json:api"
              },
              "links": {
                "self": "http://example.com/article/42"
              }
            }
          ]
        }
      }
    }
  ]
}

My idea:

Use a query parameter like

http://example.com/author?relationship[]=article,orderby=date,asc=true,limit=3

tl;dr:

What is the proper way to limit/paginate related resources in the JSON:API format?

The spec does not cover pagination and sorting of included related resources. I would recommend to not include the related resources but using a relationship link instead if you need pagination or sorting for them. The downside is having an additional request...

Beside of that I noticed that your response is not complaint with JSON:API. For resource linkage a resource identifier object (has-one) or a list of resource identifier objects (has-many) must be used.

You are using full resource objects. The difference is the attributes and links keys. Linked resource objects may be included in the response using a compound document.

Your idea using a query param to allow the client to control the inclusion of related resources is actually part of the spec. It uses the include query parameter therefore. This is described in detail in Inclusion of Related Resources chapter of the spec. But as said before that does not cover pagination and sorting of the included ressources.