[Proposal] Dependency references

[goncalo-oliveira]

When including a dependency on the schema, the way that dependency is added to the model, is up to the implementation of the resource. The C# implementation as an usage example.

It could be interesting if we could do this without requiring any code on the server side, by indicating the location of the dependency. For this example purposes let's consider the following related resources, a user

GET /users/10
---
{
    "id": 10,
    "name": "John Doe",
    "dob": "1990-01-23",
    "phoneNumber": "55000000000",
    "email": "[email protected]"
}

And a user's teams

GET /users/10/teams
---
[
    {
        "id": 13,
        "name": "Marketing"
    },
    {
        "id": 18,
        "name": "Employees"
    }
]

To combine both into a single requests, here's how the schema could look like

{
   "spec": {
      "_": ["id", "name", "teams"]
   },
   "refs": {
        "teams": {
            "url": "/users/{id}/teams"
        }
    }
}

This would be instructing the API to retrieve the data from the /users/{id}/teams resource and add the result into the teams property.

This could be extended to resources outside the requested API, which could be very useful for micro APIs environments, although I would say we should limit this to "known" locations. For example

{
   "spec": {
      "_": ["id", "name", "teams"]
   },
   "refs": {
        "teams": {
            "url": "//teams/teams?userId={id}"
        }
    }
}

The //teams in the url is a reference to a known location, under the name teams, that internally would be translated to an external API or micro API. These known locations would be set up by the API.

When requesting the dependency resource, the API would use the same headers (except for schema ones). So, if there's any authorization, it is assumed the same would work for the dependency request. However, we could further extend the schema to include additional headers in the dependency request, such as

{
   "spec": {
      "_": ["id", "name", "teams"]
   },
   "refs": {
        "teams": {
            "url": "//teams/teams?userId={id}",
            "headers": {
                "Authorization": "Bearer 9440cabd83712d0498fdc8ae1849af"
            }
        }
    }
}

There are some concerns around what we could add to the resulting model;

• Should we restrict this only to properties that exist in the model?
• Should we let the implementation decide which dependencies to allow, something like "resource known dependencies"?
• Should we enforce the resulting model?
• Should we limit the number of dependencies in a single request?