|2019-11-03, 09:02 PM||رقم المشاركة :1|
English News & Topics
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.
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.
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.
There are a few known bugs related to the API, here's a notable one:
API: can't get comments belonging to an article #2250
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-securit...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:
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:
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-securit...it-s-evil-47d5
View on GitHub
Open feature requests
A few outstanding feature requests, for example:
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:
API docs: add OpenAPI documentation to undocumented routes #4474
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/d...ocs/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
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:
We could also integrate a validator like speccy to make sure that the API doc file gets validated at each commit.
View on GitHub
We plan to keep the community updated with a changelog post from now on, for every change related to the API.
|مواقع النشر (المفضلة)|
|الكلمات الدلالية (Tags)|
|2019, [, ], api, documentation, endpoints, october or november, of, state, the|
|انواع عرض الموضوع|