Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow requests to "expand" links #141

Open
thomasplevy opened this issue Nov 13, 2019 · 0 comments
Open

Allow requests to "expand" links #141

thomasplevy opened this issue Nov 13, 2019 · 0 comments
Labels
Type: Documentation Issue related to documentation Type: Enhancement Improvements existing features or code
Milestone

Comments

@thomasplevy
Copy link
Contributor

thomasplevy commented Nov 13, 2019

In order to provide a better API consumer experience when using applications like Zapier we should provide a way to "expand" related objects on various API resources.

For example, when retrieving information about a student enrollment many API consumers may want information about the related post or student (or both).

With an "expand" parameter consumers may specify which resources should be expanded and we could add these resources to the return.

An example response is currently:

{
  "student_id": 123,
  "post_id": 456,
  "date_created": "2019-05-21 14:22:05",
  "date_updated": "2019-05-21 19:22:05",
  "status": "enrolled",
  "_links": { ... }
}

An expanded response could add expanded resources as follows:

{
  "student_id": 123,
  "post_id": 456,
  "date_created": "2019-05-21 14:22:05",
  "date_updated": "2019-05-21 19:22:05",
  "status": "enrolled",
  "_links": { ... },
  "_expanded": {
      "student": { ... },
      "post": { ... }
  },
}

I think that essentially any resource which references another resource could utilize and "expanded" request parameter.

Stripe's API expands items inline, however since most of our endpoints respond with "student_id" instead of "student" I don't think it makes semantic sense to add an object to a property that has "_id" in the name.

The Rebilly API handles things more the way I think we should: https://rebilly.github.io/RebillyAPI/#section/Expand-to-Include-Embedded-Objects

I do, however, like the way Stripe allows you to recursively request expanded objects. This would be useful on the Student Progress api. If, for example, you're consuming progress updates about a lesson you could expand the post as well as that lesson's parent course via the course_id property.

@thomasplevy thomasplevy added language: php Type: Documentation Issue related to documentation Type: Enhancement Improvements existing features or code labels Nov 13, 2019
@thomasplevy thomasplevy added this to the Future milestone Nov 13, 2019
@thomasplevy thomasplevy moved this to Awaiting Triage in Development Apr 21, 2022
@thomasplevy thomasplevy moved this from Awaiting Triage to Backlog in Development Apr 21, 2022
@thomasplevy thomasplevy moved this from Backlog to To do in Development Apr 21, 2022
@thomasplevy thomasplevy moved this from To do to Backlog in Development Jul 6, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Type: Documentation Issue related to documentation Type: Enhancement Improvements existing features or code
Projects
Status: Backlog
Development

No branches or pull requests

1 participant