maverick/docbrown
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
docbrown/docs/api_v0.yml
Andy Zhao 955bdcb2bc
Update docs with Forem instead of dev.to (#9316) 
* Rename all GitHub links from thepracticaldev/dev.to to forem/forem

* Use new site name

* Rename to Forem

* Rename more dev.to to forem

* Remove unnecessary redirects

* Rename DEV to Forem

* Use Forem instead of DEV for branding

* Use Forem instead of DEV for licensing

* Use seedling instead of DEV logo
2020-07-15 13:29:11 -04:00

3124 lines
99 KiB
YAML
Raw Blame History

# This document follows the OpenAPI spec <https://spec.openapis.org/oas/v3.0.3>
# It contains two Redoc vendor extensions, x-code-samples and x-logo
# x-logo: https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#x-logo
# x-code-samples: https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#x-code-samples
openapi: "3.0.3"
info:
title: DEV API (beta)
description: |
Access DEV articles, users and other resources via API.
All endpoints that don't require authentication are CORS enabled.
Dates and date times, unless otherwise specified, must be in
the [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
version: "0.7.0"
termsOfService: https://dev.to/terms
contact:
name: DEV Team
url: https://dev.to/contact
email: yo@dev.to
x-logo:
url: https://practicaldev-herokuapp-com.freetls.fastly.net/assets/devlogo-pwa-128-1a9016906487b8ba17f2d3d3c28f9d1cb3ae9b45d685cc2711e20f6b3c6730df.png
backgroundColor: "#000"
altText: "DEV logo"
servers:
- url: https://dev.to/api
description: Production server
components:
parameters:
pageParam:
in: query
name: page
required: false
description: Pagination page.
schema:
type: integer
format: int32
minimum: 1
default: 1
perPageParam10to1000:
in: query
name: per_page
required: false
description: Page size (the number of items to return per page).
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 10
perPageParam24to1000:
in: query
name: per_page
required: false
description: Page size (the number of items to return per page).
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 24
perPageParam30to1000:
in: query
name: per_page
required: false
description: Page size (the number of items to return per page).
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 30
perPageParam80to1000:
in: query
name: per_page
required: false
description: Page size (the number of items to return per page).
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 80
securitySchemes:
api_key:
type: apiKey
description: |
API Key authentication.
Authentication for some endpoints, like write operations on the
Articles API require a DEV API key.
### Getting an API key
To obtain one, please follow these steps:
- visit https://dev.to/settings/account
- in the "DEV API Keys" section create a new key by adding a
description and clicking on "Generate API Key"
![obtain a DEV API Key](https://user-images.githubusercontent.com/146201/64421366-af3f8b00-d0a1-11e9-8ff6-7cc0ca6e854e.png)
- You'll see the newly generated key in the same view
![generated DEV API Key](https://user-images.githubusercontent.com/146201/64421367-af3f8b00-d0a1-11e9-9831-73d3bdfdff66.png)
name: api-key
in: header
oauth2:
type: oauth2
description: |
OAuth2 authentication.
OAuth2 authentication is still in private alpha.
flows:
authorizationCode:
authorizationUrl: https://dev.to/oauth/authorize
tokenUrl: https://dev.to/oauth/token
refreshUrl: https://dev.to/oauth/token
scopes: {}
clientCredentials:
tokenUrl: https://dev.to/oauth/token
refreshUrl: https://dev.to/oauth/token
scopes: {}
schemas:
APIError:
type: object
required:
- error
- status
properties:
error:
type: string
status:
type: integer
format: int32
ArticleIndex:
type: object
required:
- type_of
- id
- title
- description
- cover_image
- readable_publish_date
- social_image
- tag_list
- tags
- slug
- path
- url
- canonical_url
- comments_count
- public_reactions_count
- created_at
- edited_at
- crossposted_at
- published_at
- last_comment_at
- published_timestamp
- user
properties:
type_of:
type: string
id:
type: integer
format: int32
title:
type: string
description:
type: string
cover_image:
type: string
format: url
readable_publish_date:
type: string
social_image:
type: string
format: url
tag_list:
type: array
items:
type: string
tags:
type: string
slug:
type: string
path:
type: string
format: path
url:
type: string
format: url
canonical_url:
type: string
format: url
comments_count:
type: integer
format: int32
public_reactions_count:
type: integer
format: int32
created_at:
type: string
format: date-time
edited_at:
type: string
format: date-time
crossposted_at:
type: string
format: date-time
published_at:
type: string
format: date-time
last_comment_at:
type: string
format: date-time
published_timestamp:
description: Crossposting or published date time
type: string
format: date-time
user:
$ref: "#/components/schemas/SharedUser"
organization:
$ref: "#/components/schemas/SharedOrganization"
flare_tag:
$ref: "#/components/schemas/ArticleFlareTag"
ArticleShow:
type: object
required:
- type_of
- id
- title
- description
- cover_image
- readable_publish_date
- social_image
- tag_list
- tags
- slug
- path
- url
- canonical_url
- comments_count
- public_reactions_count
- created_at
- edited_at
- crossposted_at
- published_at
- last_comment_at
- published_timestamp
- body_html
- body_markdown
- user
properties:
type_of:
type: string
id:
type: integer
format: int32
title:
type: string
description:
type: string
cover_image:
type: string
format: url
readable_publish_date:
type: string
social_image:
type: string
format: url
tag_list:
type: string
tags:
type: array
items:
type: string
slug:
type: string
path:
type: string
format: path
url:
type: string
format: url
canonical_url:
type: string
format: url
comments_count:
type: integer
format: int32
public_reactions_count:
type: integer
format: int32
created_at:
type: string
format: date-time
edited_at:
type: string
format: date-time
crossposted_at:
type: string
format: date-time
published_at:
type: string
format: date-time
last_comment_at:
type: string
format: date-time
published_timestamp:
description: Crossposting or published date time
type: string
format: date-time
body_html:
type: string
body_markdown:
type: string
user:
$ref: "#/components/schemas/SharedUser"
organization:
$ref: "#/components/schemas/SharedOrganization"
flare_tag:
$ref: "#/components/schemas/ArticleFlareTag"
ArticleCreate:
type: object
properties:
article:
type: object
required:
- title
properties:
title:
type: string
body_markdown:
description: |
The body of the article.
It can contain an optional front matter. For example
```markdown
---
title: Hello, World!
published: true
tags: discuss, help
date: 20190701T10:00Z
series: Hello series
canonical_url: https://example.com/blog/hello
cover_image: article_published_cover_image
---
```
`date`, `series` and `canonical_url` are optional.
`date` is the publication date-time
`series` is the name of the series the article belongs to
`canonical_url` is the canonical URL of the article
`cover_image` is the main image of the article
*If the markdown contains a front matter, it will take precedence
on the equivalent params given in the payload.*
type: string
published:
description: |
True to create a published article, false otherwise. Defaults to false
type: boolean
series:
description: |
Article series name.
All articles belonging to the same series need to have the same name
in this parameter.
type: string
main_image:
type: string
format: url
canonical_url:
type: string
format: url
description:
type: string
tags:
type: array
items:
type: string
organization_id:
description: |
Only users belonging to an organization can assign the article to it
type: integer
format: int32
ArticleUpdate:
type: object
properties:
article:
type: object
properties:
title:
type: string
body_markdown:
description: |
The body of the article.
It can contain an optional front matter. For example
```markdown
---
title: Hello, World!
published: true
tags: discuss, help
date: 20190701T10:00Z
series: Hello series
canonical_url: https://example.com/blog/hello
cover_image: article_published_cover_image
---
```
`date`, `series` and `canonical_url` are optional.
`date` is the publication date-time
`series` is the name of the series the article belongs to
`canonical_url` is the canonical URL of the article
`cover_image` is the main image of the article
*If the markdown contains a front matter, it will take precedence
on the equivalent params given in the payload.*
type: string
published:
description: |
True to create a published article, false otherwise. Defaults to false
type: boolean
series:
description: |
Article series name.
All articles belonging to the same series need to have the same name
in this parameter.
To remove an article from a series, the `null` value can be used.
type: string
main_image:
type: string
format: url
canonical_url:
type: string
format: url
description:
type: string
tags:
type: array
items:
type: string
organization_id:
description: |
Only users belonging to an organization can assign the article to it
type: integer
format: int32
ArticleMe:
type: object
required:
- type_of
- id
- title
- description
- cover_image
- published
- published_at
- tag_list
- slug
- path
- url
- canonical_url
- comments_count
- public_reactions_count
- page_views_count
- published_timestamp
- body_markdown
- user
properties:
type_of:
type: string
id:
type: integer
format: int32
title:
type: string
description:
type: string
cover_image:
type: string
format: url
published:
type: boolean
published_at:
type: string
format: date-time
tag_list:
type: array
items:
type: string
slug:
type: string
path:
type: string
format: path
url:
type: string
format: url
canonical_url:
type: string
format: url
comments_count:
type: integer
format: int32
public_reactions_count:
type: integer
format: int32
page_views_count:
type: integer
format: int32
published_timestamp:
description: Crossposting or published date time
type: string
format: date-time
body_markdown:
description: The body of the article in Markdown format
type: string
user:
$ref: "#/components/schemas/SharedUser"
organization:
$ref: "#/components/schemas/SharedOrganization"
flare_tag:
$ref: "#/components/schemas/ArticleFlareTag"
ArticleFlareTag:
description: Flare tag of the article
type: object
properties:
name:
type: string
bg_color_hex:
description: Background color (hexadecimal)
type: string
text_color_hex:
description: Text color (hexadecimal)
type: string
ArticleVideo:
type: object
required:
- type_of
- id
- path
- cloudinary_video_url
- title
- user_id
- video_duration_in_minutes
- user
properties:
type_of:
type: string
id:
type: integer
format: int32
path:
type: string
cloudinary_video_url:
description: The preview image of the video
type: string
format: url
title:
type: string
user_id:
type: integer
format: int32
video_duration_in_minutes:
description: |
The duration of the video.
If the video duration is below 1 hour, the format will be `mm:ss`,
if it's 1 hour or above the format will be `h:mm:ss`.
type: string
user:
type: object
properties:
name:
description: The user's name
type: string
Comment:
type: object
required:
- type_of
- id_code
- body_html
- user
- children
properties:
type_of:
type: string
id_code:
type: string
body_html:
description: HTML formatted comment
type: string
user:
$ref: "#/components/schemas/SharedUser"
children:
type: array
items:
$ref: "#/components/schemas/Comment"
Follower:
type: object
required:
- type_of
- id
- name
- path
- username
- profile_image
properties:
type_of:
type: string
id:
description: Follow id
type: integer
format: int32
name:
type: string
path:
type: string
username:
type: string
profile_image:
description: Profile image (60x60)
type: string
format: url
Listing:
type: object
required:
- type_of
- id
- title
- slug
- body_markdown
- tag_list
- tags
- category
- processed_html
- published
- user
properties:
type_of:
type: string
id:
type: integer
format: int64
title:
type: string
slug:
type: string
body_markdown:
type: string
tag_list:
type: string
tags:
type: array
items:
type: string
category:
$ref: "#/components/schemas/ListingCategory"
processed_html:
type: string
published:
type: boolean
user:
$ref: "#/components/schemas/SharedUser"
organization:
$ref: "#/components/schemas/SharedOrganization"
ListingCategory:
type: string
enum: [cfp, forhire, collabs, education, jobs, mentors, products, mentees, forsale, events, misc]
ListingCreate:
type: object
properties:
listing:
type: object
required:
- title
- body_markdown
- category
properties:
title:
type: string
body_markdown:
description: The body of the listing in Markdown format.
type: string
category:
$ref: "#/components/schemas/ListingCategory"
tags:
description: |
Tags related to the listing.
A maximum of 8 tags are allowed and it takes precedence over `tag_list`.
type: array
items:
type: string
tag_list:
description: |
Comma separated list of tags.
A maximum of 8 tags are allowed.
type: string
expires_at:
description: Date and time of expiration.
type: string
format: date-time
contact_via_connect:
description: |
True if users are allowed to contact the listing's owner
via DEV connect, false otherwise.
Defaults to false.
type: boolean
location:
description: Geographical area or city for the listing.
type: string
organization_id:
description: |
The id of the organization the user is creating the listing for.
Only users belonging to an organization can assign the listing to it.
type: integer
format: int64
action:
description: Set it to "draft" to create an unpublished listing
type: string
enum: [draft]
ListingUpdate:
type: object
properties:
listing:
type: object
properties:
title:
type: string
body_markdown:
description: The body of the listing in Markdown format.
type: string
category:
$ref: "#/components/schemas/ListingCategory"
tags:
description: |
Tags related to the listing.
A maximum of 8 tags are allowed and it takes precedence over `tag_list`.
type: array
items:
type: string
tag_list:
description: |
Comma separated list of tags.
A maximum of 8 tags are allowed.
type: string
expires_at:
description: Date and time of expiration.
type: string
format: date-time
contact_via_connect:
description: |
True if users are allowed to contact the listing's owner
via DEV connect, false otherwise.
Defaults to false.
type: boolean
location:
description: Geographical area or city for the listing.
type: string
action:
description: |
This param can be provided by itself to invoke some actions:
- `bump` bumps the listing and charge either the
organization or the user
- `publish` publishes a draft listing
- `unpublish` unpublishes a published listing
It will take priority on any other param in the payload.
type: string
enum: [bump, publish, unpublish]
PodcastEpisode:
type: object
required:
- type_of
- id
- path
- image_url
- title
- podcast
properties:
type_of:
type: string
id:
type: integer
format: int32
path:
type: string
image_url:
type: string
format: url
title:
type: string
podcast:
type: object
properties:
title:
type: string
slug:
type: string
image_url:
type: string
format: url
SharedUser:
description: The resource creator
type: object
properties:
name:
type: string
username:
type: string
twitter_username:
type: string
github_username:
type: string
website_url:
type: string
format: url
profile_image:
description: Profile image (640x640)
type: string
profile_image_90:
description: Profile image (90x90)
type: string
SharedOrganization:
description: The organization the resource belongs to
type: object
properties:
name:
type: string
username:
type: string
slug:
type: string
profile_image:
description: Profile image (640x640)
type: string
format: url
profile_image_90:
description: Profile image (90x90)
type: string
format: url
Tag:
type: object
required:
- id
- name
- bg_color_hex
- text_color_hex
properties:
id:
type: integer
format: int32
name:
type: string
bg_color_hex:
description: Background color (hexadecimal)
type: string
text_color_hex:
description: Text color (hexadecimal)
type: string
User:
type: object
required:
- type_of
- id
- username
- name
- summary
- twitter_username
- github_username
- website_url
- location
- joined_at
- profile_image
properties:
type_of:
type: string
id:
type: integer
format: int32
username:
type: string
name:
type: string
summary:
type: string
twitter_username:
type: string
github_username:
type: string
website_url:
type: string
format: url
location:
type: string
joined_at:
description: Date of joining (formatted with strftime `"%b %e, %Y"`)
type: string
profile_image:
description: Profile image (320x320)
type: string
format: url
WebhookCreate:
description: Webhook creation payload
type: object
properties:
webhook_endpoint:
type: object
required:
- source
- target_url
- events
properties:
source:
description: The name of the requester, eg. "DEV"
type: string
target_url:
type: string
format: url
events:
description: An array of events identifiers
type: array
items:
type: string
WebhookIndex:
description: Webhook
type: object
properties:
type_of:
type: string
id:
type: integer
format: int64
source:
description: The name of the requester, eg. "DEV"
type: string
target_url:
type: string
format: url
events:
description: An array of events identifiers
type: array
items:
type: string
created_at:
type: string
format: date-time
WebhookShow:
description: Webhook
type: object
properties:
type_of:
type: string
id:
type: integer
format: int64
source:
description: The name of the requester, eg. "DEV"
type: string
target_url:
type: string
format: url
events:
description: An array of events identifiers
type: array
items:
type: string
created_at:
type: string
format: date-time
user:
$ref: "#/components/schemas/SharedUser"
examples:
ErrorBadRequest:
value:
error: bad request
status: 400
ErrorNotFound:
value:
error: not found
status: 404
ErrorUnauthorized:
value:
error: unauthorized
status: 401
ErrorPaymentRequired:
value:
error: not enough available credits
status: 402
ErrorForbidden:
value:
error: forbidden
status: 403
ErrorUnprocessableEntity:
value:
error: "param is missing or the value is empty: article"
status: 422
ErrorTooManyRequests:
value:
error: "Rate limit reached, try again in 30 seconds"
status: 429
ArticlesIndex:
value:
- type_of: article
id: 194541
title: There's a new DEV theme in town for all you 10x hackers out there (plus one
actually useful new feature)
description: ''
cover_image: https://res.cloudinary.com/practicaldev/image/fetch/s--74Bl23tz--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://res.cloudinary.com/practicaldev/image/fetch/s--xU8cbIK4--/c_imagga_scale%2Cf_auto%2Cfl_progressive%2Ch_420%2Cq_auto%2Cw_1000/https://thepracticaldev.s3.amazonaws.com/i/8a39dzf3oovzc2snl7iv.png
readable_publish_date: Oct 24
social_image: https://res.cloudinary.com/practicaldev/image/fetch/s--SeMxdKIa--/c_imagga_scale,f_auto,fl_progressive,h_500,q_auto,w_1000/https://res.cloudinary.com/practicaldev/image/fetch/s--xU8cbIK4--/c_imagga_scale%2Cf_auto%2Cfl_progressive%2Ch_420%2Cq_auto%2Cw_1000/https://thepracticaldev.s3.amazonaws.com/i/8a39dzf3oovzc2snl7iv.png
tag_list:
- meta
- changelog
- css
- ux
tags: meta, changelog, css, ux
slug: there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
path: "/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk"
url: https://dev.to/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
canonical_url: https://dev.to/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
comments_count: 37
public_reactions_count: 142
collection_id:
created_at: '2019-10-24T13:41:29Z'
edited_at: '2019-10-24T13:56:35Z'
crossposted_at:
published_at: '2019-10-24T13:52:17Z'
last_comment_at: '2019-10-25T08:12:43Z'
published_timestamp: '2019-10-24T13:52:17Z'
user:
name: Ben Halpern
username: ben
twitter_username: bendhalpern
github_username: benhalpern
website_url: http://benhalpern.com
profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--Y1sq1tFG--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/1/f451a206-11c8-4e3d-8936-143d0a7e65bb.png
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--DcW51A6v--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/1/f451a206-11c8-4e3d-8936-143d0a7e65bb.png
organization:
name: The DEV Team
username: devteam
slug: devteam
profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--0kDBq1Ne--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/1/0213bbaa-d5a1-4d25-9e7a-10c30b455af0.png
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--8tTU-XkZ--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/1/0213bbaa-d5a1-4d25-9e7a-10c30b455af0.png
ArticleShow:
value:
type_of: article
id: 150589
title: "Byte Sized Episode 2: The Creation of Graph Theory "
description: The full story of Leonhard Euler and the creation of this fundamental
computer science principle, delivered in a few minutes.
cover_image: https://res.cloudinary.com/practicaldev/image/fetch/s--qgutBUrH--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://thepracticaldev.s3.amazonaws.com/i/88e62fzblbluz1dm7xjf.png
readable_publish_date: Aug 1
social_image: https://res.cloudinary.com/practicaldev/image/fetch/s--6wSHHfwd--/c_imagga_scale,f_auto,fl_progressive,h_500,q_auto,w_1000/https://thepracticaldev.s3.amazonaws.com/i/88e62fzblbluz1dm7xjf.png
tag_list: computerscience, graphtheory, bytesized, history
tags:
- computerscience
- graphtheory
- bytesized
- history
slug: byte-sized-episode-2-the-creation-of-graph-theory-34g1
path: "/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1"
url: https://dev.to/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1
canonical_url: https://dev.to/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1
comments_count: 21
public_reactions_count: 322
collection_id: 1693
created_at: "2019-07-31T11:15:06Z"
edited_at:
crossposted_at:
published_at: "2019-08-01T15:47:54Z"
last_comment_at: "2019-08-06T16:48:10Z"
published_timestamp: "2019-08-01T15:47:54Z"
body_html: |+
<p>Today's episode of Byte Sized is about Leonhard Euler and the creation of <a href="https://en.wikipedia.org/wiki/Graph_theory">Graph Theory</a>.</p>
<p>For more about how Graph Theory works, check out this video from BaseCS!</p>...
body_markdown: "---\r\ntitle: Byte Sized Episode 2: The Creation of Graph Theory \r\npublished:
true\r\ndescription: The full story of Leonhard Euler and the creation of this fundamental
computer science principle, delivered in a few minutes.\r\ntags: computerscience,
graphtheory, bytesized, history\r\ncover_image: https://thepracticaldev.s3.amazonaws.com/i/88e62fzblbluz1dm7xjf.png\r\nseries:
Byte Sized Season 1\r\n---\r\n\r\nToday's episode of Byte Sized is about Leonhard
Euler and the creation of [Graph Theory](https://en.wikipedia.org/wiki/Graph_theory).\r\n\r\nFor
more about how Graph Theory works, check out this video from BaseCS!..."
user:
name: Vaidehi Joshi
username: vaidehijoshi
twitter_username: vaidehijoshi
github_username: vaidehijoshi
website_url: http://www.vaidehi.com
profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--eDGAYAoK--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2882/K2evUksb.jpg
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--htZnqMn3--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2882/K2evUksb.jpg
organization:
name: Byte Sized
username: bytesized
slug: bytesized
profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--sq0DrZfn--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/865/652f7998-32a8-4fd9-85ca-dd697d2a9ee9.png
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--1Pt_ICL---/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/865/652f7998-32a8-4fd9-85ca-dd697d2a9ee9.png
ArticleCreateTitleBody:
value:
article:
title: Hello, World!
published: true
body_markdown: Hello DEV, this is my first post
tags: ["discuss", "help"]
series: Hello series
canonical_url: https://example.com/blog/hello
ArticleCreateFrontMatter:
value:
article:
body_markdown: |
---
title: Hello, World!
published: true
tags: discuss, help
date: 20190701T10:00Z
series: Hello series
canonical_url: https://example.com/blog/hello
---
Hello DEV, this is my first post
ArticleCreateOrganization:
value:
article:
title: Hello, World!
published: true
body_markdown: Hello DEV, this is my first post
tags: ["discuss", "help"]
series: Hello series
canonical_url: https://example.com/blog/hello
organization_id: 1234
ArticleVideo:
value:
- type_of: video_article
id: 273532
path: "/devteam/basecs-depth-first-search-implementing-4kkl"
cloudinary_video_url: https://res.cloudinary.com/....png
title: 'BaseCS: Depth First Search Implementing'
user_id: 2882
video_duration_in_minutes: '11:47'
user:
name: Vaidehi Joshi
Comments:
value:
- type_of: comment
id_code: m3m0
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
</body></html>
user:
name: Heriberto Morissette
username: heriberto_morissette
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...jpeg
profile_image_90: https://res.cloudinary.com/...jpeg
children: []
- type_of: comment
id_code: m357
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
<p>...</p>
</body></html>
user:
name: Dario Waelchi
username: dario waelchi
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...png
profile_image_90: https://res.cloudinary.com/...png
children:
- type_of: comment
id_code: m35m
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
</body></html>
user:
name: rhymes
username: rhymes
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...jpeg
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--SC90PuMi--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg
children: []
CommentsDeleted:
value:
- type_of: comment
id_code: m357
body_html: <p>[deleted]</p>
user: {}
children:
- type_of: comment
id_code: m35m
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
</body></html>
user:
name: rhymes
username: rhymes
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...jpeg
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--SC90PuMi--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg
children: []
CommentsHidden:
value:
- type_of: comment
id_code: m357
body_html: <p>[hidden by post author]</p>
user: {}
children:
- type_of: comment
id_code: m35m
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
</body></html>
user:
name: rhymes
username: rhymes
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...jpeg
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--SC90PuMi--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg
children: []
Comment:
value:
type_of: comment
id_code: m357
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
<p>...</p>
</body></html>
user:
name: Dario Waelchi
username: dario waelchi
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...png
profile_image_90: https://res.cloudinary.com/...png
children:
- type_of: comment
id_code: m35m
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
</body></html>
user:
name: rhymes
username: rhymes
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...jpeg
profile_image_90: https://res.cloudinary.com/....jpeg
children: []
CommentDeleted:
value:
type_of: comment
id_code: m357
body_html: <p>[deleted]</p>
user: {}
children:
- type_of: comment
id_code: m35m
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
</body></html>
user:
name: rhymes
username: rhymes
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...jpeg
profile_image_90: https://res.cloudinary.com/...jpeg
children: []
CommentHidden:
value:
type_of: comment
id_code: m357
body_html: <p>[hidden by post author]</p>
user: {}
children:
- type_of: comment
id_code: m35m
body_html: |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><body>
<p>...</p>
</body></html>
user:
name: rhymes
username: rhymes
twitter_username:
github_username:
website_url:
profile_image: https://res.cloudinary.com/...jpeg
profile_image_90: https://res.cloudinary.com/...jpeg
children: []
Followers:
value:
- type_of: user_follower
id: 12
name: Mrs. Neda Morissette
path: "/nedamrsmorissette"
username: nedamrsmorissette
profile_image: https://res.cloudinary.com/...
- type_of: user_follower
id: 11
name: Yoko Hintz
path: "/yokohintz"
username: yokohintz
profile_image: https://res.cloudinary.com/...
Listings:
value:
- type_of: listing
id: 1157
title: TestBash Detroit
slug: testbash-detroit-50gb
body_markdown: "Do you want to learn about automation? Maybe you're interested in
AI-driven testing? Security testing? We have a selection of talks, workshops and
training courses to help you in a wide variety of areas in software testing. Join
us for our very first trip to Detroit MI! \n\nhttps://bit.ly/TBDetroit"
tag_list: events
tags:
- events
category: cfp
processed_html: |
<p>Do you want to learn about automation? Maybe you're interested in AI-driven testing? Security testing? We have a selection of talks, workshops and training courses to help you in a wide variety of areas in software testing. Join us for our very first trip to Detroit MI! </p>
<p><a href="https://bit.ly/TBDetroit">https://bit.ly/TBDetroit</a></p>
published: true
user:
name: Heather
username: heatherr
twitter_username:
github_username: Heather-R
website_url:
profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--ggU5WPaT--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--CjladMBD--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
Listing:
value:
type_of: listing
id: 1157
title: TestBash Detroit
slug: testbash-detroit-50gb
body_markdown: "Do you want to learn about automation? Maybe you're interested in
AI-driven testing? Security testing? We have a selection of talks, workshops and
training courses to help you in a wide variety of areas in software testing. Join
us for our very first trip to Detroit MI! \n\nhttps://bit.ly/TBDetroit"
tag_list: events
tags:
- events
category: cfp
processed_html: |
<p>Do you want to learn about automation? Maybe you're interested in AI-driven testing? Security testing? We have a selection of talks, workshops and training courses to help you in a wide variety of areas in software testing. Join us for our very first trip to Detroit MI! </p>
<p><a href="https://bit.ly/TBDetroit">https://bit.ly/TBDetroit</a></p>
published: true
user:
name: Heather
username: heatherr
twitter_username:
github_username: Heather-R
website_url:
profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--ggU5WPaT--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--CjladMBD--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
ListingCreate:
value:
listing:
title: ACME Conference
body_markdown: Awesome conference
category: cfp
tags:
- events
ListingCreateOrganization:
value:
listing:
title: ACME Conference
body_markdown: Awesome conference
category: cfp
tags:
- events
organization_id: 1
ListingUpdate:
value:
listing:
title: ACME New Conference
body_markdown: Awesome new conference
ListingUpdateActionBump:
value:
listing:
action: bump
ListingUpdateActionPublish:
value:
listing:
action: publish
ListingUpdateActionUnpublish:
value:
listing:
action: unpublish
PodcastEpisodes:
value:
- type_of: podcast_episodes
id: 13894
path: "/codenewbie/s11-e7-why-site-reliability-is-so-important-molly-struve"
image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png
title: S11:E7 - Why site reliability is so important (Molly Struve)
podcast:
title: CodeNewbie
slug: codenewbie
image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png
- type_of: podcast_episodes
id: 13829
path: "/codenewbie/s11-e6-what-are-the-pros-and-cons-of-working-in-civic-tech-aidan-feldman"
image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png
title: S11:E6 - What are the pros and cons of working in civic tech (Aidan Feldman)
podcast:
title: CodeNewbie
slug: codenewbie
image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png
Tags:
value:
- id: 6
name: javascript
bg_color_hex: "#F7DF1E"
text_color_hex: "#000000"
- id: 8
name: webdev
bg_color_hex: "#562765"
text_color_hex: "#ffffff"
User:
value:
type_of: user
id: 1234
username: bob
name: bob
summary: Hello, world
twitter_username: bob
github_username: bob
website_url:
location: New York
joined_at: Jan 1, 2017
profile_image: https://res.cloudinary.com/...jpeg
WebhookCreate:
value:
webhook_endpoint:
target_url: https://example.com/webhooks/webhook1
source: DEV
events:
- article_created
WebhookShow:
value:
type_of: webhook_endpoint
id: 1
source: DEV
target_url: https://example.com/webhooks/webhook1
events:
- article_created
created_at: "2019-09-02T09:47:39.230Z"
user:
name: bob
username: bob
twitter_username:
github_username: bob
website_url:
profile_image: "..."
profile_image_90: "..."
tags:
- name: articles
description: Articles are all the posts users create on DEV
- name: comments
description: Users can leave comments to articles and podcasts episodes
- name: followers
description: Users can follow other users on the website
- name: listings
description: Listings are classified ads
- name: podcast-episodes
description: Podcast episodes
- name: tags
description: Tags for articles
- name: users
description: Users own resources that require authentication
- name: videos
description: Video articles
- name: webhooks
description: Webhooks are HTTP endpoints registered to receive events
paths:
/articles:
get:
operationId: getArticles
summary: Published articles
description: |
This endpoint allows the client to retrieve a list of articles.
"Articles" are all the posts that users create on DEV that typically
show up in the feed. They can be a blog post, a discussion question,
a help thread etc. but is referred to as article within the code.
By default it will return featured, published articles ordered
by descending popularity.
It supports pagination, each page will contain `30` articles by default.
tags:
- articles
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
- name: tag
in: query
description: |
Using this parameter will retrieve articles that contain the
requested tag.
Articles will be ordered by descending popularity.
This parameter can be used in conjuction with `top`.
schema:
type: string
example: discuss
- name: username
in: query
description: |
Using this parameter will retrieve articles belonging
to a User or Organization ordered by descending publication date.
If `state=all` the number of items returned will be `1000` instead of the default `30`.
This parameter can be used in conjuction with `state`.
schema:
type: string
example: ben
- name: state
in: query
description: |
Using this parameter will allow the client to check which articles are fresh or rising.
If `state=fresh` the server will return fresh articles.
If `state=rising` the server will return rising articles.
This param can be used in conjuction with `username`, only if set to `all`.
schema:
type: string
enum: [fresh, rising, all]
example: fresh
- name: top
in: query
description: |
Using this parameter will allow the client to return the most popular articles
in the last `N` days.
`top` indicates the number of days since publication of the articles
returned.
This param can be used in conjuction with `tag`.
schema:
type: integer
format: int32
minimum: 1
example: 2
- name: collection_id
in: query
description: |
Adding this will allow the client to return the list of articles
belonging to the requested collection, ordered by ascending
publication date.
schema:
type: integer
format: int32
example: 99
responses:
"200":
description: A list of articles
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ArticleIndex"
examples:
articles-success:
$ref: "#/components/examples/ArticlesIndex"
x-code-samples:
- lang: Shell
label: curl (all articles)
source: |
curl https://dev.to/api/articles
- lang: Shell
label: curl (user's articles)
source: |
curl https://dev.to/api/articles?username=ben
post:
operationId: createArticle
summary: Create a new article
description: |
This endpoint allows the client to create a new article.
"Articles" are all the posts that users create on DEV that typically
show up in the feed. They can be a blog post, a discussion question,
a help thread etc. but is referred to as article within the code.
### Rate limiting
There is a limit of 10 requests per 30 seconds.
### Additional resources
- [Rails tests for Articles API](https://github.com/forem/forem/blob/master/spec/requests/api/v0/articles_spec.rb)
tags:
- articles
requestBody:
description: Article to create
content:
application/json:
schema:
$ref: "#/components/schemas/ArticleCreate"
examples:
article-create-title-body:
$ref: "#/components/examples/ArticleCreateTitleBody"
article-create-front-matter:
$ref: "#/components/examples/ArticleCreateFrontMatter"
article-create-organization:
$ref: "#/components/examples/ArticleCreateOrganization"
responses:
"201":
description: A newly created article
content:
application/json:
schema:
$ref: "#/components/schemas/ArticleShow"
examples:
article-success:
$ref: "#/components/examples/ArticleShow"
headers:
Location:
description: The URL of the new article
schema:
type: string
format: url
"400":
description: BadRequest
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-bad-request:
$ref: "#/components/examples/ErrorBadRequest"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-forbidden:
$ref: "#/components/examples/ErrorForbidden"
"422":
description: Unprocessable Entity
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unprocessable-entity:
$ref: "#/components/examples/ErrorUnprocessableEntity"
"429":
description: Too Many Requests
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unprocessable-entity:
$ref: "#/components/examples/ErrorTooManyRequests"
headers:
Retry-After:
description: The number of seconds to wait until the next request
schema:
type: integer
format: int32
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -X POST -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"article":{"title":"Title","body_markdown":"Body","published":false,"tags":["discuss", "javascript"]}}' \
https://dev.to/api/articles
- lang: Shell
label: curl (with front matter)
source: |
curl -X POST -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"article":{"body_markdown":"---\ntitle:A sample article about...\npublished:false\n---\n..."}}' \
https://dev.to/api/articles
/articles/{id}:
parameters:
- name: id
in: path
required: true
description: Id of the article
schema:
type: integer
format: int32
minimum: 1
example: 150589
get:
operationId: getArticleById
summary: A published article by ID
description: |
This endpoint allows the client to retrieve a single
published article given its `id`.
tags:
- articles
responses:
"200":
description: An article
content:
application/json:
schema:
$ref: "#/components/schemas/ArticleShow"
examples:
article-success:
$ref: "#/components/examples/ArticleShow"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
x-code-samples:
- lang: Shell
label: curl
source: |
curl https://dev.to/api/articles/150589
put:
operationId: updateArticle
summary: Update an article
description: |
This endpoint allows the client to update an existing article.
"Articles" are all the posts that users create on DEV that typically
show up in the feed. They can be a blog post, a discussion question,
a help thread etc. but is referred to as article within the code.
### Rate limiting
There is a limit of 150 requests per 30 seconds.
### Additional resources
- [Rails tests for Articles API](https://github.com/forem/forem/blob/master/spec/requests/api/v0/articles_spec.rb)
tags:
- articles
requestBody:
description: |
Article params for the update.
*Note: if the article contains a front matter in its body, its front
matter properties will still take precedence over any JSON equivalent
params, which means that the full body_markdown with the modified
front matter params needs to be provided for an update to be successful*
content:
application/json:
schema:
$ref: "#/components/schemas/ArticleUpdate"
examples:
article-update-title-body:
$ref: "#/components/examples/ArticleCreateTitleBody"
article-update-front-matter:
$ref: "#/components/examples/ArticleCreateFrontMatter"
article-update-organization:
$ref: "#/components/examples/ArticleCreateOrganization"
responses:
"200":
description: The updated article
content:
application/json:
schema:
$ref: "#/components/schemas/ArticleShow"
examples:
article-success:
$ref: "#/components/examples/ArticleShow"
"400":
description: BadRequest
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-bad-request:
$ref: "#/components/examples/ErrorBadRequest"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-forbidden:
$ref: "#/components/examples/ErrorForbidden"
"422":
description: Unprocessable Entity
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unprocessable-entity:
$ref: "#/components/examples/ErrorUnprocessableEntity"
"429":
description: Too Many Requests
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unprocessable-entity:
$ref: "#/components/examples/ErrorTooManyRequests"
headers:
Retry-After:
description: The number of seconds to wait until the next request
schema:
type: integer
format: int32
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -X PUT -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"article":{"title":"Title"}}' \
https://dev.to/api/articles/{id}
/articles/{username}/{slug}:
parameters:
- name: username
in: path
required: true
description: User or organization username.
schema:
type: string
example: devteam
- name: slug
in: path
required: true
description: Slug of the article.
schema:
type: string
example: for-empowering-community-2k6h
get:
operationId: getArticleByPath
summary: A published article by path
description: |
This endpoint allows the client to retrieve a single
published article given its `path`.
tags:
- articles
responses:
"200":
description: An article
content:
application/json:
schema:
$ref: "#/components/schemas/ArticleShow"
examples:
article-success:
$ref: "#/components/examples/ArticleShow"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
x-code-samples:
- lang: Shell
label: curl
source: |
curl https://dev.to/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1
/articles/me:
get:
operationId: getUserArticles
summary: User's articles
description: |
This endpoint allows the client to retrieve a list of published articles
on behalf of an authenticated user.
"Articles" are all the posts that users create on DEV that typically
show up in the feed. They can be a blog post, a discussion question,
a help thread etc. but is referred to as article within the code.
Published articles will be in reverse chronological publication order.
It will return published articles with pagination.
By default a page will contain `30` articles.
tags:
- articles
- users
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
responses:
"200":
description: A list of published articles
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ArticleMe"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -H "api-key: API_KEY" https://dev.to/api/articles/me
/articles/me/published:
get:
operationId: getUserPublishedArticles
summary: User's published articles
description: |
This endpoint allows the client to retrieve a list of published articles
on behalf of an authenticated user.
"Articles" are all the posts that users create on DEV that typically
show up in the feed. They can be a blog post, a discussion question,
a help thread etc. but is referred to as article within the code.
Published articles will be in reverse chronological publication order.
It will return published articles with pagination.
By default a page will contain `30` articles.
tags:
- articles
- users
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
responses:
"200":
description: A list of published articles
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ArticleMe"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -H "api-key: API_KEY" https://dev.to/api/articles/me/published
/articles/me/unpublished:
get:
operationId: getUserUnpublishedArticles
summary: User's unpublished articles
description: |
This endpoint allows the client to retrieve a list of unpublished articles
on behalf of an authenticated user.
"Articles" are all the posts that users create on DEV that typically
show up in the feed. They can be a blog post, a discussion question,
a help thread etc. but is referred to as article within the code.
Unpublished articles will be in reverse chronological creation order.
It will return unpublished articles with pagination.
By default a page will contain `30` articles.
tags:
- articles
- users
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
responses:
"200":
description: A list of articles
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ArticleMe"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -H "api-key: API_KEY" https://dev.to/api/articles/me/unpublished
/articles/me/all:
get:
operationId: getUserAllArticles
summary: User's all articles
description: |
This endpoint allows the client to retrieve a list of all articles on
behalf of an authenticated user.
"Articles" are all the posts that users create on DEV that typically
show up in the feed. They can be a blog post, a discussion question,
a help thread etc. but is referred to as article within the code.
It will return both published and unpublished articles with pagination.
Unpublished articles will be at the top of the list in reverse chronological creation order.
Published articles will follow in reverse chronological publication order.
By default a page will contain `30` articles.
tags:
- articles
- users
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
responses:
"200":
description: A list of articles
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ArticleMe"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -H "api-key: API_KEY" https://dev.to/api/articles/me/all
/comments:
get:
operationId: getCommentsByArticleId
summary: Comments
description: |
This endpoint allows the client to retrieve all comments belonging to an
article as threaded conversations.
It will return the all top level comments with their nested comments as
threads. See the format specification for further details.
tags:
- comments
parameters:
- name: a_id
in: query
description: Article identifier.
schema:
type: integer
format: int32
minimum: 1
example: 270180
responses:
"200":
description: A list of threads of comments
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Comment"
examples:
comments-success:
$ref: "#/components/examples/Comments"
comments-success-deleted:
$ref: "#/components/examples/CommentsDeleted"
comments-success-hidden:
$ref: "#/components/examples/CommentsHidden"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
x-code-samples:
- lang: Shell
label: curl (all comments of an article)
source: |
curl https://dev.to/api/comments?a_id=270180
/comments/{id}:
get:
operationId: getCommentById
summary: Comment
description: |
This endpoint allows the client to retrieve a comment as well as his
descendants comments.
It will return the required comment (the root) with its nested
descendants as a thread.
See the format specification for further details.
tags:
- comments
parameters:
- name: id
in: path
required: true
description: Comment identifier.
schema:
type: string
example: m35m
responses:
"200":
description: A comment and its descendants
content:
application/json:
schema:
$ref: "#/components/schemas/Comment"
examples:
comment-success:
$ref: "#/components/examples/Comment"
comments-success-deleted:
$ref: "#/components/examples/CommentDeleted"
comments-success-hidden:
$ref: "#/components/examples/CommentHidden"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
x-code-samples:
- lang: Shell
label: curl (a comment and its descendants)
source: |
curl https://dev.to/api/comments/m51e
/followers/users:
get:
operationId: getFollowers
summary: Followers
description: |
This endpoint allows the client to retrieve a list of the followers
they have.
"Followers" are users that are following other users on the website.
It supports pagination, each page will contain `80` followers by default.
tags:
- followers
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam80to1000'
responses:
"200":
description: A list of followers
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Follower"
examples:
followers-success:
$ref: "#/components/examples/Followers"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
security:
- api_key: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -H "api-key: API_KEY" https://dev.to/api/followers/users
/listings:
get:
operationId: getListings
summary: Published listings
description: |
This endpoint allows the client to retrieve a list of listings.
"Listings" are classified ads that users create on DEV.
They can be related to conference announcements, job offers, mentorships,
upcoming events and more.
By default it will return published listings ordered by descending
freshness.
It supports pagination, each page will contain `30` articles by default.
tags:
- listings
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
- name: category
in: query
description: |
Using this parameter will return listings belonging to the
requested category.
schema:
type: string
example: cfp
responses:
"200":
description: A list of listings
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Listing"
examples:
listings-success:
$ref: "#/components/examples/Listings"
x-code-samples:
- lang: Shell
label: curl (all listings)
source: |
curl https://dev.to/api/listings
post:
operationId: createListing
summary: Create a new listing
description: |
This endpoint allows the client to create a new listing.
"Listings" are classified ads that users create on DEV.
They can be related to conference announcements, job offers, mentorships,
upcoming events and more.
The user creating the listing or the organization on which behalf the user
is creating for need to have enough creadits for this operation to be
successful. The server will prioritize the organization's credits over
the user's credits.
### Additional resources
- [Rails tests for Listings API](https://github.com/forem/forem/blob/master/spec/requests/api/v0/listings_spec.rb)
tags:
- listings
requestBody:
description: Listing to create
content:
application/json:
schema:
$ref: "#/components/schemas/ListingCreate"
examples:
listing-create:
$ref: "#/components/examples/ListingCreate"
listing-create-organization:
$ref: "#/components/examples/ListingCreateOrganization"
responses:
"201":
description: A newly created Listing
content:
application/json:
schema:
$ref: "#/components/schemas/Listing"
examples:
article-success:
$ref: "#/components/examples/Listing"
"400":
description: BadRequest
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-bad-request:
$ref: "#/components/examples/ErrorBadRequest"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
"402":
description: PaymentRequired
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorPaymentRequired"
"422":
description: Unprocessable Entity
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unprocessable-entity:
$ref: "#/components/examples/ErrorUnprocessableEntity"
security:
- api_key: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -X POST -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"listing":{"title":"Title","body_markdown":"Body","category":"cfp"}}' \
https://dev.to/api/listings
- lang: Shell
label: curl (with tags)
source: |
curl -X POST -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"listing":{"title":"Title","body_markdown":"Body","category":"cfp","tags":["python"]}}' \
https://dev.to/api/listings
- lang: Shell
label: curl (draft)
source: |
curl -X POST -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"listing":{"title":"Title","body_markdown":"Body","category":"cfp","action":"draft"}}' \
https://dev.to/api/listings
/listings/category/{category}:
get:
operationId: getListingsByCategory
summary: Published listings by category
description: |
This endpoint allows the client to retrieve a list of listings belonging
to the specified category.
"Listings" are classified ads that users create on DEV.
They can be related to conference announcements, job offers, mentorships,
upcoming events and more.
By default it will return published listings ordered by descending
freshness.
It supports pagination, each page will contain `30` articles by default.
tags:
- listings
parameters:
- name: category
in: path
required: true
description: The category of the listing
schema:
$ref: "#/components/schemas/ListingCategory"
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
responses:
"200":
description: A list of listings
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Listing"
examples:
listings-success:
$ref: "#/components/examples/Listings"
x-code-samples:
- lang: Shell
label: curl (call for papers listings)
source: |
curl https://dev.to/api/listings/category/cfp
/listings/{id}:
parameters:
- name: id
in: path
required: true
description: Id of the listing
schema:
type: integer
format: int64
minimum: 1
example: 1
get:
operationId: getListingById
summary: A listing
description: |
This endpoint allows the client to retrieve
a single listing given its `id`.
An unpublished listing is only accessible if authentication is supplied
and it belongs to the authenticated user.
tags:
- listings
responses:
"200":
description: A listing
content:
application/json:
schema:
$ref: "#/components/schemas/Listing"
examples:
article-success:
$ref: "#/components/examples/Listing"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
security:
- {} # this indicates that authentication is optional
- api_key: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl https://dev.to/api/listings/1184
- lang: Shell
label: curl (with authentication)
source: |
curl -H "api-key: API_KEY" https://dev.to/api/listings/1185
put:
operationId: updateListing
summary: Update a listing
description: |
This endpoint allows the client to update an existing listing.
tags:
- listings
requestBody:
description: |
Listing params for the update.
**Note**: except for bumping, publishing and unpublishing there are the
following restrictions on the ability to update listings:
- the payload has to contain at least one param among `title`, `body_markdown` or `tags`/`tag_list`
- the listing can't be updated if it has not been bumped in the last 24 hours
- the listing can't be updated if it has been published but not recently bumped
content:
application/json:
schema:
$ref: "#/components/schemas/ListingUpdate"
examples:
listing-update-action-bump:
$ref: "#/components/examples/ListingUpdateActionBump"
listing-update-action-publish:
$ref: "#/components/examples/ListingUpdateActionPublish"
listing-update-action-unpublish:
$ref: "#/components/examples/ListingUpdateActionUnpublish"
listing-update:
$ref: "#/components/examples/ListingUpdate"
responses:
"200":
description: The updated article
content:
application/json:
schema:
$ref: "#/components/schemas/ArticleShow"
examples:
article-success:
$ref: "#/components/examples/ArticleShow"
"400":
description: BadRequest
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-bad-request:
$ref: "#/components/examples/ErrorBadRequest"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
"402":
description: PaymentRequired
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorPaymentRequired"
"422":
description: Unprocessable Entity
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unprocessable-entity:
$ref: "#/components/examples/ErrorUnprocessableEntity"
security:
- api_key: []
x-code-samples:
- lang: Shell
label: curl (bump)
source: |
curl -X PUT -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"listing":{"action":"bump"}' \
https://dev.to/api/listings/{id}
- lang: Shell
label: curl (update)
source: |
curl -X PUT -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"listing":{"title":"Title"}' \
https://dev.to/api/listings/{id}
/podcast_episodes:
get:
operationId: getPodcastEpisodes
summary: Published podcast episodes
description: |
This endpoint allows the client to retrieve a list of podcast episodes.
"Podcast episodes" are episodes belonging to podcasts.
It will only return active podcast episodes that belong to published
podcasts available on the platform,
ordered by descending publication date.
It supports pagination, each page will contain `30` articles by default.
tags:
- podcast-episodes
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam30to1000'
- name: username
in: query
description: |
Using this parameter will retrieve episodes belonging
to a specific podcast.
schema:
type: string
example: codenewbie
responses:
"200":
description: A list of podcast episodes
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PodcastEpisode"
examples:
articles-success:
$ref: "#/components/examples/PodcastEpisodes"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
x-code-samples:
- lang: Shell
label: curl (all podcast episodes)
source: |
curl https://dev.to/api/podcast_episodes
- lang: Shell
label: curl (all episodes belonging to a podcast)
source: |
curl https://dev.to/api/podcast_episodes?username=codenewbie
/tags:
get:
operationId: getTags
summary: Tags
description: |
This endpoint allows the client to retrieve a list of tags
that can be used to tag articles.
It will return tags ordered by popularity.
It supports pagination, each page will contain `10` tags by default.
tags:
- tags
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam10to1000'
responses:
"200":
description: A list of tags
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Tag"
examples:
articles-success:
$ref: "#/components/examples/Tags"
x-code-samples:
- lang: Shell
label: curl (all tags)
source: |
curl https://dev.to/api/tags
/users/{id}:
get:
operationId: getUser
summary: A user
description: |
This endpoint allows the client to retrieve a single user, either by
id or by the user's username
tags:
- users
parameters:
- name: id
in: path
required: true
description: |
Id of the user.
It can be either of the following two values:
- an integer representing the id of the user
- the string `by_username` (needs to be used in conjuction with the param `url`)
schema:
type: string
example: "1"
- name: url
in: query
description: Username of the user
schema:
type: string
example: ben
responses:
"200":
description: A user
content:
application/json:
schema:
$ref: "#/components/schemas/User"
examples:
user-success:
$ref: "#/components/examples/User"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
user-not-found:
$ref: "#/components/examples/ErrorNotFound"
x-code-samples:
- lang: Shell
label: curl (by id)
source: |
curl https://dev.to/api/users/1
- lang: Shell
label: curl (by username)
source: |
curl https://dev.to/api/users/by_username?url=ben
/users/me:
get:
operationId: getUserMe
summary: The authenticated user
description: |
This endpoint allows the client to retrieve information
about the authenticated user
tags:
- users
responses:
"200":
description: A user
content:
application/json:
schema:
$ref: "#/components/schemas/User"
examples:
user-success:
$ref: "#/components/examples/User"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -H "api-key: API_KEY" https://dev.to/api/users/me
/videos:
get:
operationId: getArticlesWithVideo
summary: Articles with a video
description: |
This endpoint allows the client to retrieve a list of articles
that are uploaded with a video.
It will only return published video articles
ordered by descending popularity.
It supports pagination, each page will contain `24` articles by default.
tags:
- articles
- videos
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam24to1000'
responses:
"200":
description: A list of video articles
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ArticleVideo"
examples:
articles-success:
$ref: "#/components/examples/ArticleVideo"
x-code-samples:
- lang: Shell
label: curl (all video articles)
source: |
curl https://dev.to/api/videos
/webhooks:
get:
operationId: getWebhooks
summary: Webhooks
description: |
This endpoint allows the client to retrieve a list of webhooks they have
previously registered.
"Webhooks" are used to register HTTP endpoints that will be called once a relevant event is
triggered inside the web application, events like `article_created`, `article_updated`.
It will return all webhooks, without pagination.
tags:
- webhooks
responses:
"200":
description: A list of webhooks
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/WebhookIndex"
examples:
webhooks-success:
summary: Successful response
value:
- type_of: webhook_endpoint
id: 1
source: DEV
target_url: https://example.com/webhooks/webhook1
events:
- article_created
created_at: "2019-09-02T09:47:39.230Z"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -H "api-key: API_KEY" https://dev.to/api/webhooks
post:
operationId: createWebhook
summary: Create a new webhook
description: |
This endpoint allows the client to create a new webhook.
"Webhooks" are used to register HTTP endpoints that will be called once a relevant event is
triggered inside the web application, events like `article_created`, `article_updated`.
tags:
- webhooks
requestBody:
description: Webhook to create
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookCreate"
examples:
webhook-create:
$ref: "#/components/examples/WebhookCreate"
responses:
"201":
description: A newly created webhook
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookShow"
examples:
webhook-success:
$ref: "#/components/examples/WebhookShow"
"400":
description: BadRequest
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-bad-request:
$ref: "#/components/examples/ErrorBadRequest"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
"422":
description: Unprocessable Entity
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
error-unprocessable-entity:
$ref: "#/components/examples/ErrorUnprocessableEntity"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -X POST -H "Content-Type: application/json" \
-H "api-key: API_KEY" \
-d '{"webhook_endpoint":{"target_url":"https://example.org/webhooks/webhook1","source":"DEV","events":["article_created"]}}' \
https://dev.to/api/webhooks
/webhooks/{id}:
parameters:
- name: id
in: path
required: true
description: Id of the webhook
schema:
type: integer
format: int64
minimum: 1
example: 123
get:
operationId: getWebhookById
summary: A webhook endpoint
description: |
This endpoint allows the client to retrieve a single
webhook given its `id`.
tags:
- webhooks
responses:
"200":
description: A webhook endpoint
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookShow"
examples:
webhook-success:
$ref: "#/components/examples/WebhookShow"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl https://dev.to/api/webhooks/123
delete:
operationId: deleteWebhook
summary: A webhook endpoint
description: |
This endpoint allows the client to delete a single
webhook given its `id`.
tags:
- webhooks
responses:
"204":
description: A successful deletion
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-unauthorized:
$ref: "#/components/examples/ErrorUnauthorized"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/APIError"
examples:
article-not-found:
$ref: "#/components/examples/ErrorNotFound"
security:
- api_key: []
- oauth2: []
x-code-samples:
- lang: Shell
label: curl
source: |
curl -X DELETE \
-H "api-key: API_KEY" \
https://dev.to/api/webhooks/1
Reference in a new issue View git blame Copy permalink