API: Return properties regarding series in GET request data

[cdvillard]

Is your feature request related to a problem? Please describe.

When creating articles using the API, it's possible to assign the article to a series. However, when querying for articles from the API, no information regarding series is made available in either the objects returned /api/articles/?=${queryString} or the data returned from /api/articles/${id}.

Describe the solution you'd like

Ideally, a series property would be returned along with the rest of the data for each article from either endpoint with the title or some other identifier of the series to which the article belongs.

Describe alternatives you've considered

Additional context

[benhalpern]

Series names are not unique, so this would probably require params for the user and the series name. So I think something like /api/articles/?collection=${id} (series is actually a "type" of collection, it just so happens we haven't built any other collection types yet.)

We could expose this ID in the other APIs so that people could first query that to get an id.

We could also have a collections controller which takes an ID and responds with a json array of articles. We could make both available.

[cyrillefr]

Hello @benhalpern , I would like to volunteer for this one.

[rhymes]

@cyrillefr to keep things small maybe you could do it in steps, first a PR to add collection ids to articles and the ability to filter articles by those ids, then a separate PR with a controller to get the list of collections that a user has

makes sense?

[cyrillefr]

Hello @rhymes, sorry for the delay. I will do it that way then, in two parts.

[beeman]

@cyrillefr did you end up working on this?

I'm happy to start working on this as I'd really like the API to return info about the Series.

[cyrillefr]

Hello @beeman , sorry for the delay.
I must say I have a bit forgotten about that one.
So yes, go ahead.

[matisnape]

@rhymes can I try finish this one? :)

[matisnape]

@rhymes I started working on this.
Question regarding separate PR with a controller to get the list of collections that a user has - how this should be served? /api/users/{id}/collections? or /api/articles/me/collections?

[rhymes]

Thanks @matisnape, this is a bit tricky indeed. The goal here is to return the series a user has.

I think we could mirror the website - eg. https://dev.to/rhymes/series - with something like dev.to/api/users/:id/series and list them there.

As I think we made a mistake exposing collection_id in #4180 instead of calling it series_id, we might want to call this /series but I'd like to discuss this internally before finalizing (we could also add series_id in addition to collection_id to the articles controller but that's probably for another PR)

[matisnape]

@rhymes Regarding content of the endpoint response - the discussion above mentions IDs only. I suppose there should be serialized user details, like with the other endpoints? Anything else that should be included?

[rhymes]

mmm @matisnape I'm not sure we should serialize the user properties, they don't add much to the representation of the series, after all we're in a "sub directory" of /users/:id. In addition we can always add things to endpoints, it's harder to remove already exposed fields.

Looking at the collections table I think we could expose creation date, slug and published articles count for now

What do you think?

[cmgorton]

Since this issue has gone stale I am going to close it. If anyone would like to still implement this feature let me know and we can turn this issue into a discussion