DEV strives towards being open, collaborative, and a positive force in the larger ecosystem.
Anyone can generate an API key from their own user's account and start playing with it.
Some endpoints, like the list of the recently published articles, are public - https://dev.to/api/articles - and require no authentication.
Currently the API has three authentication mechanisms: API keys, OAuth2 (in private testing and limited only to some endpoints) and the HTTP session (only on those endpoints accessed by dev.to's frontend).
API keys will allow you to access both public and private endpoints.
OAuth2 is intended for third party apps that need to request data on behalf of an authenticated user.
The API was initially developed in the pre open source days to serve internal needs and was slowly opened to the public, adding API keys support to serve private endpoints.
The API v0 is in beta. We are committed to not breaking any of the existing interfaces or responses, which means that any possible quirks related to those are there to stay until the next version.
Though we don't currently have a deprecation policy in place for v0, we do know that we don't want to remove or change endpoints, remove fields or change their type, or do anything else that would automatically break clients.
We have several endpoints related to resources that you might recognize: articles, comments, chat channels, videos, podcasts, tags, listings, analytics (in private testing) and of course, users.
The API is edge cached, which means that it can occasionally respond with stale content. That said, the advantage to this approach is that the source of the data is near you. Some endpoints are additionally cached server side — usually those that require a lot of computation.
The API v0 could use improvement on the following fronts: fixing bugs, adding missing resources/features, adding needed fields to existing resources, improving documentation and better caching.
There are a few known bugs related to the API, here's a notable one:
Describe the bug
I can't seem to be able to retrieve articles comments from the DEV API. It works on my local installation but not using the live API.
Given the article API response https://dev.to/api/articles/95907 - https://dev.to/kathyra_/what-security-through-obscurity-is-and-why-it-s-evil-47d5 - I tried to retrieve its comments using https://dev.to/api/comments?a_id=95907 but the server returns
At a first glance it should work, according to the code:
The odd thing is that such call works correctly on a local installation.
I'm probably doing something wrong on my end.
To Reproduce Steps to reproduce the behavior:
- Go to https://dev.to/api/comments?a_id=95907
- See error
I'd expect this endpoint to return all the comments of the article with id
95907 which should be the following: https://dev.to/kathyra_/what-security-through-obscurity-is-and-why-it-s-evil-47d5
A few outstanding feature requests, for example:
- Filtering articles by tag
Adding series to the API: we can currently filter by the ID of the series, but we lack
CRUDoperations on those
- Adding video upload to the API: right now video upload is only available through an async process via the website's UI
The API docs are written in
YAML, following the OpenAPI 3.0 spec. From there a script generates automatically the HTML and it gets updated at each deploy.
What is lacking now is actual documentation on most of the endpoints, I've opened a "meta" issue listing all in detail:
Is your feature request related to a problem? Please describe.
The API docs are incomplete. Right now they only document endpoints under
Describe the solution you'd like
Many different endpoints, resources and responses are missing, the goal is to arrive to a documentation as complete as possible.
The documentation file is https://github.com/thepracticaldev/dev.to/blob/master/docs/api_v0.yml
There are a couple of requirements if we want to complete this documentation effort: knowledge of OpenAPI and coordination.
To get acquainted with OpenAPI I suggest two resources: the official OpenAPI 3 spec and the OpenAPI guide by Swagger.io. The first one contains all the info, the second one is helpful when in doubt about how to do things.
Also read the Contributing to the API spec docs page, in there you can find information about Visual Studio Code extensions that can help and how to serve the API docs locally for testing (remember to refresh the browser page at each change :)).
To coordinate I'm going to leave here the list of missing endpoints and then I'll explain where to find their code and their tests:
Endpoints to document
GET /api/comments api/v0/comments#index
GET /api/comments/:id api/v0/comments#show
GET /api/followers/users api/v0/followers#users
GET /api/listings api/v0/classified_listings#index
POST /api/listings api/v0/classified_listings#create
GET /api/listings/:id api/v0/classified_listings#show
PUT /api/listings/:id api/v0/classified_listings#update
GET /api/listings/category/:category api/v0/classified_listings#index
GET /api/podcast_episodes api/v0/podcast_episodes#index
GET /api/tags api/v0/tags#index
GET /api/users/:id api/v0/users#show
GET /api/users/me api/v0/users#me
GET /api/videos api/v0/videos#index
For example, you can find the code for
GET /api/comments inside the file https://github.com/thepracticaldev/dev.to/blob/master/app/controllers/api/v0/comments_controller.rb in the action
index. Its test would be in https://github.com/thepracticaldev/dev.to/blob/master/spec/requests/api/v0/comments_spec.rb
I also suggest to scan the API doc file to understand how is it structured and play around with
curl or other tools like Postwoman, so you can see how the responses are, for example:
curl https://dev.to/api/comments/gi9b (jq is a great companion if you use the command line)
Don't forget to bump the version in your PR.
Please declare which endpoint(s) you're going to document, we have to be extra careful to avoid having conflicts in the documentation effort.
A couple of tips: you'll probably find bugs or inconsistencies while documenting, please open separate issues for those, keeping in mind that the policy we have is:
- inconsistencies that don't break the API can be fixed, please open issues and separate PRs for those, PRs tied to this ticket are only about documentation
- any inconsistencies that you think should be known by the API docs reader can be documented
- possible caching bugs, or other bugs, are hiding around the API, please open separate issues for those as well. There are already some documented cases of API bugs here: https://github.com/thepracticaldev/dev.to/issues?q=is%3Aissue+is%3Aopen+label%3A%22area%3A+api-v0%22
Don't forget to read the contributing guide and please use the following schema for your PRs:
USERNAME/DESCRIPTION-4474 (4474 is the ID of this very issue, it makes the reviewer's job easier to know which branch belongs to whom and to which issues refers to)
We could also integrate a validator like speccy to make sure that the API doc file gets validated at each commit.
We plan to keep the community updated with a changelog post from now on, for every change related to the API.