Changelog: API updates

We recently shipped a series of improvements to the Forem API thanks to our open source contributors:

• Fetching articles by their slugs
• Fetching podcast episodes comments
• Retrieving a list of followed tags
• Getting the list of articles in the reading list
• Finding organizations details

Read on to find more about these changes!

Thanks to Oghenebrume50 we can fetch an article by its slug:

Fetch article by slug #8929

Oghenebrume50 posted on Jun 26, 2020

What type of PR is this? (check all applicable)

• [ ] Refactor
• [X] Feature
• [ ] Bug Fix
• [ ] Optimization
• [ ] Documentation Update

Description

According to this issue #8313 the user suggested that articles should be searchable by slug and not only by id. My implement included converting the param input to an integer, so if a string that is not a valid number is passed it returns 0. So if the value is not zero then I find with the id else I find by the slug, in both cases, the error is well handled by rails, this is why I used find_by! instead of find_by because the former return an ActiveRecord::ActiveRecordError when nothing is found

QA Instructions, Screenshots, Recordings

This is an example of a working slug

Example of a wrong slug that is not found

Also, the id works fine

I tested everything, all possible endpoints and they work fine.

I am opening this as a draft PR to check if this is a good approach, if this is okay I can update the documentation.

Please replace this line with instructions on how to test your changes, as well as any relevant images for UI changes.

Added tests?

• [ ] yes
• [x] no, because they aren't needed
• [ ] no, because I need help

Added to documentation?

• [ ] docs.dev.to
• [ ] readme
• [x] no documentation needed

View on GitHub

You can find more information in the documentation and try it here: https://dev.to/api/articles/devteam/the-7-most-popular-dev-posts-from-the-past-week-4fhi

Thanks to jkrsn98 we can retrieve a podcast episode’s comments:

API: retrieve podcast episodes comments #9677

jkrsn98 posted on Aug 07, 2020

What type of PR is this? (check all applicable)

• [ ] Refactor
• [x] Feature
• [ ] Bug Fix
• [ ] Optimization
• [ ] Documentation Update

Description

Modified the index in comments controller which previously only handled look for a_id parameter, to having it look for a_id or p_id parameter which allow for accessing podcast episode comments. If a_id key has value, it looks for article with that id, if a_id has no value, then it must be that user is trying to query with p_id, so it looks for podcast episode.

Related Tickets & Documents

Fixes #6526

QA Instructions, Screenshots, Recordings

Currently you can only request comments related to articles with parameter a_id

With the line I modified it now uses parameter p_id as well, which will return all the comments related to the podcast episode with that id, same behaviour as was for articles For example, with the following podcast episode with id 1, I comment on it then try to query with that id, and it works as follows

Added tests?

• [x] yes
• [ ] no, because they aren't needed
• [ ] no, because I need help

Added to documentation?

• [x] docs.forem.com
• [ ] readme
• [ ] no documentation needed

View on GitHub

You can find more information in the documentation and try it here: https://dev.to/api/comments?p_id=15564

jkrsn98 also added the missing created_at field in comments that will help determine when a comment was posted on the website:

API: add created_at datetime to comments #9829

jkrsn98 posted on Aug 17, 2020

What type of PR is this? (check all applicable)

• [ ] Refactor
• [x] Feature
• [ ] Bug Fix
• [ ] Optimization
• [ ] Documentation Update

Description

Added created_at field for comments in api response

Related Tickets & Documents

Fixes #6095

QA Instructions, Screenshots, Recordings

Currently when user requests api/comment they do not see when each comment was created

Now that information is included:

Added tests?

• [x] yes
• [ ] no, because they aren't needed
• [ ] no, because I need help

Added to documentation?

• [x] docs.forem.com
• [ ] readme
• [ ] no documentation needed

View on GitHub

Thanks to danascheider, a user can retrieve a list of the tags they follow:

API: Add route for fetching a user's followed tags #9108

danascheider posted on Jul 03, 2020

What type of PR is this? (check all applicable)

• [ ] Refactor
• [x] Feature
• [ ] Bug Fix
• [ ] Optimization
• [ ] Documentation Update

Description

This PR adds the /api/tags/me route, which returns the authenticated user's followed tags as JSON.

Related Tickets & Documents

Closes #5111

QA Instructions, Screenshots, Recordings

I've added request specs for requests with and without valid authentication.

Added tests?

• [x] yes
• [ ] no, because they aren't needed
• [ ] no, because I need help

Added to documentation?

• [ ] docs.dev.to
• [ ] readme
• [x] no documentation needed

View on GitHub

You can find more information in the documentation

Thanks to bhacaz a user can retrieve a list of articles in their reading list.

API - New endpoint to retrieve the articles in the reading list of the authenticated user #10540

Bhacaz posted on Oct 02, 2020

What type of PR is this? (check all applicable)

• [ ] Refactor
• [x] Feature
• [ ] Bug Fix
• [ ] Optimization
• [x] Documentation Update

Description

Add a new endpoint in the DEV API to retrieve the reading list articles for the authenticated user.

GET api/articles/me/readinglist

Related Tickets & Documents

This feature was requested in Issue #6755.

QA Instructions, Screenshots, Recordings

You can try the new API endpoint via a curl command with a valid api-key.

curl -H "api-key: API-KEY" http://localhost:3000/api/readinglist 

Added tests?

• [x] yes
• [ ] no, because they aren't needed
• [ ] no, because I need help

Added to documentation?

• [x] docs.forem.com/api
• [ ] readme
• [ ] no documentation needed

What gif best describes this PR or how it makes you feel?

View on GitHub

You can find more information in the documentation.

Thanks to diogoosorio we can retrieve the profile image of a user or an organization.

Introduce /api/profile_images/:username endpoint #10547

diogoosorio posted on Oct 04, 2020

What type of PR is this? (check all applicable)

• [ ] Refactor
• [x] Feature
• [ ] Bug Fix
• [ ] Optimization
• [ ] Documentation Update

Description

This PR aims to introduce the operation GET /api/profile_images/:username to the API.

I struggled a bit with what the contract for the operation should be (as this isn't a "resource" per se), I ended up keeping it simple and re-using the structure I saw throughout the rest of the API, when dealing with profile images:

{
  "type_of": "profile_image",
  "profile_image": "/uploads/organization/profile_image/be5e87e9-5b77-40ea-81e8-dd10c6d01146.png",
  "profile_image_90": "/uploads/organization/profile_image/be5e87e9-5b77-40ea-81e8-dd10c6d01146.png"
}

Having said that, I'm happy to refactor the contract to whatever the maintainers believe it to be the correct way to represent a profile image in this endpoint - I just ask for concrete example of what the response's payload should look like 😄 .

Related Tickets & Documents

https://github.com/forem/forem/issues/10132

QA Instructions, Screenshots, Recordings

curl "http://localhost:3000/api/profile_images/:username"

Added tests?

• [x] yes
• [ ] no, because they aren't needed
• [ ] no, because I need help

Added to documentation?

• [x] docs.forem.com
• [ ] readme
• [ ] no documentation needed

View on GitHub

You can find more information in the documentation and try it here https://dev.to/api/profile_images/devteam

Thanks to twinsfan421 we’re one step closer to having API for organizations:

API: Endpoint to get an organization's details #10931

twinsfan421 posted on Oct 19, 2020

What type of PR is this? (check all applicable)

• [ ] Refactor
• [x] Feature
• [ ] Bug Fix
• [ ] Optimization
• [ ] Documentation Update

Description

This would provide an api show endpoint dev.to/api/organizations/{org_username} to search organizations by their username.
As discussed in issue 9212, This is the first of 4 related endpoints that will include:

dev.to/api/organizations/{org_username}/users
dev.to/api/organizations/{org_username}/articles
dev.to/api/organizations/{org_username}/listings

Related Tickets & Documents

https://github.com/forem/forem/issues/9212

Added tests?

• [x] yes
• [ ] no, because they aren't needed
• [ ] no, because I need help

Added to documentation?

• [x] docs.forem.com
• [ ] readme
• [ ] no documentation needed

View on GitHub

You can find more information in the documentation and try it here: https://dev.to/api/organizations/devteam

We hope you’ll find these updates to the Forem API useful!

Comments

[James Turner]

Woooo! Great job everyone!