State of the API, October/November 2019
Tags: changelog
Published: 2019-11-01 16:03:43

DEV strives towards being open, collaborative, and a positive force in the larger ecosystem.

In addition to the platform's code being [open source][DEV repository], we also provide an [API][DEV API].

Anyone can [generate an API key](https://dev.to/settings/account) 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.

## History

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.

## Current status

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.

## Areas of improvement

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.

### Known bugs

There are a [few known bugs](https://github.com/thepracticaldev/dev.to/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22area%3A+api-v0%22+label%3A%22type%3A+bug%22) related to the API, here's a notable one:

{% github https://github.com/thepracticaldev/dev.to/issues/2250 %}

### Open feature requests

A few outstanding [feature requests](https://github.com/thepracticaldev/dev.to/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22area%3A+api-v0%22+label%3A%22type%3A+feature+request%22), for example:

- [Filtering articles by tag](https://github.com/thepracticaldev/dev.to/issues/3654)
- [Adding series to the API](https://github.com/thepracticaldev/dev.to/issues/3669): we can currently filter by the ID of the series, but we lack `CRUD` operations on those
- [Adding CORS support to the API](https://github.com/thepracticaldev/dev.to/issues/4195): ideally all public endpoints should have [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) enabled, allowing frontend code to use the API directly with JavaScript
- [Adding video upload to the API](https://github.com/thepracticaldev/dev.to/issues/4419): right now video upload is only available through an async process via the website's UI

### Documentation

The [API docs][DEV 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:

{% github https://github.com/thepracticaldev/dev.to/issues/4474 %}

## Changelog

We plan to keep the community updated with a [changelog][DEV changelog] post from now on, for every change related to the API.

[DEV API]: https://dev.to/api/
[DEV API docs]: https://docs.dev.to/api/
[DEV changelog]: https://dev.to/t/changelog
[DEV repository]: https://github.com/thepracticaldev/dev.to