How to model an Organization that has many types of Reports

1

Hi,

I’m fairly new to json api and I’m trying to understand how to model resources that have different types, which from what I’ve been reading doesn’t seem to be supported, and is probably a smell of how I’m thinking about my resources.

I have an Organization that has many types of Reports. For example and Organization can have an Hours Report and an Attendance Report.

My first thought was
GET /organizations/:id/reports
I’d want to have different “types” in the response, (“hours” and “attendance”), however I see the flaw here is that the client will have no idea of all the different types of reports that are possible.

Then I was thinking the “reports” is the name of the relationship and the related resources are of type “hours” and “attendance”. Thinking something along these lines

GET organizations/:id?include=reports&filter[reports.type]=(hours,attendance)

{
	"data": {
		"type": "organizations",
		"id": "123-org",
		"attributes": {
			"name": "the org"
		}
	},
	"relationships": {
		"reports": {
            "links": "this is a to-many relationship of different types. How do I specify the links?",
			"data": [
				{
					"type": "hours",
					"id": "abc-hours"
				}
					{
					"type": "attendance",
					"id": "xyz-attendance"
				}
			]
		}
	},
	"included": [
		{
			"type": "hours",
			"id": "abc-hours",
			"attributes": {
				"foo": "bar"
			},
			"links":{
				"self": "organizations/:id/hours/abc-hours"
			}
		},
		{
			"type": "attendance",
			"id": "xyz-attendance",
			"attributes": {
				"name": "org attendance",
				"total": 10,
				"noShows": 100,
			},
			"links":{
				"self": "organizations/:id/attendance/xyz-attendance"
			}

		}
	]
}

My questions are:

  1. Is this a clean way to model this with using the reports as the relationship, which relates many types of reports to an organization?
  2. How can I specify the links in the relationships section when I have a to-many relationship of different types?
  3. What would the “self” links be in the “included” resources? Having /organizations/:id/attendance/xyz-attendance feels wrong since there is no context that this is a report that is related to the Organization.
2

This is a fairly open-ended question, which may be why you’ve not received a response until now. The specifics matter when designing an API, and there are many questions that come to mind when reading you description of the problem.

  1. Does an organization have zero or one of any given report type, or can there be many of a specific type?

  2. Do organizations have mostly the same report types, or does that vary a lot?

  3. Does the set of report types expand frequently? Can organizations add additional report types on their own, or only in coordination with the API implementer?

Figuring out the answers for these questions may help point you in a direction that’s appropriate for your application.

Good luck!

-Fred