Your Web News in One Place

Help Webnuz

Referal links:

Sign up for GreenGeeks web hosting
November 1, 2019 04:03 pm GMT

State of the API, October/November 2019

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

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

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.

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 related to the API, here's a notable one:

GitHub logo API: can't get comments belonging to an article #2250

rhymes avatar
rhymes commented on Mar 31, 2019

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 HTTP 404.

At a first glance it should work, according to the code:

https://github.com/thepracticaldev/dev.to/blob/54ccef47669759b060370c1cde8f527ce6d39333/app/controllers/api/v0/comments_controller.rb#L15-L18

The odd thing is that such call works correctly on a local installation.

I'm probably doing something wrong on my end.

To ReproduceSteps to reproduce the behavior:

  1. Go to https://dev.to/api/comments?a_id=95907
  2. See error

Expected behavior

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

Screenshots

Screenshot 2019-03-31 at 6 50 42 PM

Open feature requests

A few outstanding feature requests, for example:

Documentation

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:

GitHub logo API docs: add OpenAPI documentation to undocumented routes #4474

rhymes avatar
rhymes commented on Oct 17, 2019

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

The API docs are incomplete. Right now they only document endpoints under /articles and /webhooks

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/chat_channels/:id api/v0/chat_channels#show
  • [ ] GET /api/videos api/v0/videos#index
  • [ ] GET /api/podcast_episodes api/v0/podcast_episodes#index
  • [ ] POST /api/reactions/onboarding api/v0/reactions#onboarding
  • [ ] POST /api/reactions api/v0/reactions#create
  • [ ] GET /api/users/me api/v0/users#me
  • [ ] GET /api/users api/v0/users#index
  • [ ] GET /api/users/:id api/v0/users#show
  • [ ] GET /api/tags/onboarding api/v0/tags#onboarding
  • [ ] GET /api/tags api/v0/tags#index
  • [ ] POST /api/follows api/v0/follows#create
  • [ ] POST /api/github_repos/update_or_create api/v0/github_repos#update_or_create
  • [ ] GET /api/github_repos api/v0/github_repos#index
  • [ ] 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/analytics/totals api/v0/analytics#totals
  • [ ] GET /api/analytics/historical api/v0/analytics#historical
  • [ ] GET /api/analytics/past_day api/v0/analytics#past_day
  • [ ] GET /api/analytics/referrers api/v0/analytics#referrers

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.

Additional context

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.

Changelog

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


Original Link: https://dev.to/devteam/state-of-the-api-october-2019-d9f

Share this article:    Share on Facebook
View Full Article

Dev To

An online community for sharing and discovering great ideas, having debates, and making friends

More About this Source Visit Dev To