From 3a45bfcc2d258c5de7cf3e0e4df732d9f28e63ee Mon Sep 17 00:00:00 2001 From: rhymes Date: Wed, 22 May 2019 18:24:53 +0200 Subject: [PATCH] API docs: Adjust document and add syntax highlight [skip ci] (#2936) * Adjust document and add syntax highlight * Add alt text to images --- app/views/pages/api.html.erb | 320 ++++++++++++++++++----------------- 1 file changed, 167 insertions(+), 153 deletions(-) diff --git a/app/views/pages/api.html.erb b/app/views/pages/api.html.erb index 6b2884090..754838771 100644 --- a/app/views/pages/api.html.erb +++ b/app/views/pages/api.html.erb @@ -12,25 +12,44 @@ API"> + + + + + <% end %>
+

DEV Articles API (beta)

-

As of May 16th 2019 DEV has released a beta version of a REST API to create or update articles. Check back to this page for all updates related to the API.

-
-
-
+

+ As of May 16th 2019 DEV has released a beta version of a REST API to create or update articles. + Check back to this page for all updates related to the API. +

+
+ +
+

About the Articles API

-

"Articles" are all the posts that users create DEV that typically show up in the feed. It can be a blog post, discussion question, help thread etc. but is referred to as article within the code. It is different from listings, comments, podcasts, etc.

+

+ "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. + They are different from listings, comments, podcasts, etc. +

@@ -46,12 +65,18 @@

  • In the DEV API Access Tokens section create a new token by adding a description and clicking on "Generate Token":

    -

    +

    +

    + DEV Access tokens page +

    • +

  • You'll see the newly generated token in the same view:

    • -

    +

    + DEV access tokens page with a generated token +

    @@ -61,11 +86,11 @@

    Here is an example of how to create an article:

    - 
    curl -X POST -H "Content-Type: application/json" \
-  -H "api-key: ACCESS_TOKEN" \
-  -d '{"article": {"title": "Title", "body_markdown": "Body", "published": false, "tags": ["discuss", "javascript"]}}' \
-  https://dev.to/api/articles
-
    +
    + 
    curl -X POST -H "Content-Type: application/json" \
+-H "api-key: ACCESS_TOKEN" \
+-d '{"article": {"title": "Title", "body_markdown": "Body", "published": false, "tags": ["discuss", "javascript"]}}' \
+https://dev.to/api/articles

    If published is set to true then the article will be live instantly.

    @@ -77,44 +102,43 @@

    In case of a successful response (HTTP 201), the full article resource will be returned to the client:

    - 
    {
-    "type_of": "article",
-    "id": 110878,
-    "title": "Title",
-    "description": "Body\n\n...",
-    "cover_image": null,
-    "readable_publish_date": null,
-    "social_image": "http://dev.to/social_previews/article/110878.png",
-    "tag_list": "discuss, javascript",
-    "tags": [
-      "discuss",
-      "javascript"
-    ],
-    "slug": "title-2bp3-temp-slug-5875367",
-    "path": "/rhymes/title-2bp3-temp-slug-5875367",
-    "url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
-    "canonical_url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
-    "comments_count": 0,
-    "positive_reactions_count": 0,
-    "created_at": "2019-05-21T13:34:26Z",
-    "edited_at": null,
-    "crossposted_at": null,
-    "published_at": null,
-    "last_comment_at": "2017-01-01T05:00:00Z",
-    "body_html": "<p>Body</p>\n\n",
-    "ltag_style": [],
-    "ltag_script": [],
-    "user": {
-      "name": "rhymes",
-      "username": "rhymes",
-      "twitter_username": "rhymes_",
-      "github_username": "rhymes",
-      "website_url": null,
-      "profile_image": "https://res.cloudinary.com/practicaldev/image/fetch/s--qhCNe-v6--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg",
-      "profile_image_90": "https://res.cloudinary.com/practicaldev/image/fetch/s--IQPhTQnb--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg"
-    }
+  
    {
+  "type_of": "article",
+  "id": 110878,
+  "title": "Title",
+  "description": "Body\n\n...",
+  "cover_image": null,
+  "readable_publish_date": null,
+  "social_image": "http://dev.to/social_previews/article/110878.png",
+  "tag_list": "discuss, javascript",
+  "tags": [
+    "discuss",
+    "javascript"
+  ],
+  "slug": "title-2bp3-temp-slug-5875367",
+  "path": "/rhymes/title-2bp3-temp-slug-5875367",
+  "url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
+  "canonical_url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
+  "comments_count": 0,
+  "positive_reactions_count": 0,
+  "created_at": "2019-05-21T13:34:26Z",
+  "edited_at": null,
+  "crossposted_at": null,
+  "published_at": null,
+  "last_comment_at": "2017-01-01T05:00:00Z",
+  "body_html": "<p>Body</p>\n\n",
+  "ltag_style": [],
+  "ltag_script": [],
+  "user": {
+    "name": "rhymes",
+    "username": "rhymes",
+    "twitter_username": "rhymes_",
+    "github_username": "rhymes",
+    "website_url": null,
+    "profile_image": "https://res.cloudinary.com/practicaldev/image/fetch/s--qhCNe-v6--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg",
+    "profile_image_90": "https://res.cloudinary.com/practicaldev/image/fetch/s--IQPhTQnb--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg"
   }
-  
    
+}

    @@ -122,11 +146,10 @@

    Just add publish_under_org as true to the JSON request:

    - 
    curl -X POST -H "Content-Type: application/json" \
-  -H "api-key: ACCESS_TOKEN" \
-  -d '{"article": {"title": "Title", "body_markdown": "Body", "published": false, "publish_under_org": true}}' \
-  https://dev.to/api/articles
-
    + 
    curl -X POST -H "Content-Type: application/json" \
+-H "api-key: ACCESS_TOKEN" \
+-d '{"article": {"title": "Title", "body_markdown": "Body", "published": false, "publish_under_org": true}}' \
+https://dev.to/api/articles

    @@ -134,25 +157,23 @@

    You can omit most JSON parameters by using the markdown front matter. So for example, if you have markdown article similar to the following:

    - 
    ---
-  title: "A sample article about JavaScript"
-  published: false
-  description: "this is a sample article about javascript"
-  tags: discuss, javascript
-  series: intro-to-javascript
-  canonical_url: canonical URL of the article
-  ---
+  
    ---
+title: "A sample article about JavaScript"
+published: false
+description: "this is a sample article about javascript"
+tags: discuss, javascript
+series: intro-to-javascript
+canonical_url: canonical URL of the article
+---
 
-  This is an intro about JavaScript
-  
    
+This is an intro about JavaScript

    you can send it within the body_markdown parameter:

    - 
    curl -X POST -H "Content-Type: application/json" \
-  -H "api-key: ACCESS_TOKEN" \
-  -d '{"article": {"body_markdown": "---\ntitle: A sample article about...\npublished: false\n...", "publish_under_org": true}}' \
-  https://dev.to/api/articles
-
    + 
    curl -X POST -H "Content-Type: application/json" \
+-H "api-key: ACCESS_TOKEN" \
+-d '{"article": {"body_markdown": "---\ntitle: A sample article about...\npublished: false\n...", "publish_under_org": true}}' \
+https://dev.to/api/articles

    The front matter will take precedence on other JSON params with the same name.

    @@ -163,15 +184,14 @@ 
    title: The title of an article (string, optional)
-  description: Description of the article (string, optional)
-  body_markdown: The Markdown body, with or without a front matter (string, required)
-  published: True if the article should be published right away, defaults to false (boolean, optional)
-  tags: A list of tags for the article (array, optional)
-  series: The name of the series the article should be published within (string, optional)
-  publish_under_org: True if the article should be placed under the organization belonging to the user creating the article, defaults to false (boolean, optional)
-  main_image: URL of the image to use as the cover (string, optional)
-  canonical_url: canonical URL of the article (string, optional)
-
    +description: Description of the article (string, optional) +body_markdown: The Markdown body, with or without a front matter (string, required) +published: True if the article should be published right away, defaults to false (boolean, optional) +tags: A list of tags for the article (array, optional) +series: The name of the series the article should be published within (string, optional) +publish_under_org: True if the article should be placed under the organization belonging to the user creating the article, defaults to false (boolean, optional) +main_image: URL of the image to use as the cover (string, optional) +canonical_url: canonical URL of the article (string, optional)

    @@ -179,19 +199,18 @@

    Unauthorized

    - 
    {
-    "error": "unauthorized",
-    "status": 401
-  }
-
    + 
    {
+  "error": "unauthorized",
+  "status": 401
+}

    Parameter validation error

    - 
    {
-    "error": "Validation failed: Title can't be blank",
-    "status": 422
-  }
-
    + 
    {
+  "error": "Validation failed: Title can't be blank",
+  "status": 422
+}
    +

    @@ -199,11 +218,11 @@

    Here is an example of how to update an article:

    - 
    curl -X PUT -H "Content-Type: application/json" \
-  -H "api-key: ACCESS_TOKEN" \
-  -d '{"article": {"title": "New Title"}}' \
-  https://dev.to/api/articles/ARTICLE_ID
-
    + 
    curl -X PUT -H "Content-Type: application/json" \
+-H "api-key: ACCESS_TOKEN" \
+-d '{"article": {"title": "New Title"}}' \
+https://dev.to/api/articles/ARTICLE_ID
    +

    @@ -211,44 +230,44 @@

    In case of a successful response (HTTP 200), the full article resource will be returned to the client:

    - 
    {
-    "type_of": "article",
-    "id": 110878,
-    "title": "New Title",
-    "description": "Body\n\n...",
-    "cover_image": null,
-    "readable_publish_date": null,
-    "social_image": "http://dev.to/social_previews/article/110878.png",
-    "tag_list": "discuss, javascript",
-    "tags": [
-      "discuss",
-      "javascript"
-    ],
-    "slug": "title-2bp3-temp-slug-5875367",
-    "path": "/rhymes/title-2bp3-temp-slug-5875367",
-    "url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
-    "canonical_url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
-    "comments_count": 0,
-    "positive_reactions_count": 0,
-    "created_at": "2019-05-21T13:34:26Z",
-    "edited_at": null,
-    "crossposted_at": null,
-    "published_at": null,
-    "last_comment_at": "2017-01-01T05:00:00Z",
-    "body_html": "<p>Body</p>\n\n",
-    "ltag_style": [],
-    "ltag_script": [],
-    "user": {
-      "name": "rhymes",
-      "username": "rhymes",
-      "twitter_username": "rhymes_",
-      "github_username": "rhymes",
-      "website_url": null,
-      "profile_image": "https://res.cloudinary.com/practicaldev/image/fetch/s--qhCNe-v6--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg",
-      "profile_image_90": "https://res.cloudinary.com/practicaldev/image/fetch/s--IQPhTQnb--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg"
-    }
+  
    {
+  "type_of": "article",
+  "id": 110878,
+  "title": "New Title",
+  "description": "Body\n\n...",
+  "cover_image": null,
+  "readable_publish_date": null,
+  "social_image": "http://dev.to/social_previews/article/110878.png",
+  "tag_list": "discuss, javascript",
+  "tags": [
+    "discuss",
+    "javascript"
+  ],
+  "slug": "title-2bp3-temp-slug-5875367",
+  "path": "/rhymes/title-2bp3-temp-slug-5875367",
+  "url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
+  "canonical_url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
+  "comments_count": 0,
+  "positive_reactions_count": 0,
+  "created_at": "2019-05-21T13:34:26Z",
+  "edited_at": null,
+  "crossposted_at": null,
+  "published_at": null,
+  "last_comment_at": "2017-01-01T05:00:00Z",
+  "body_html": "<p>Body</p>\n\n",
+  "ltag_style": [],
+  "ltag_script": [],
+  "user": {
+    "name": "rhymes",
+    "username": "rhymes",
+    "twitter_username": "rhymes_",
+    "github_username": "rhymes",
+    "website_url": null,
+    "profile_image": "https://res.cloudinary.com/practicaldev/image/fetch/s--qhCNe-v6--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg",
+    "profile_image_90": "https://res.cloudinary.com/practicaldev/image/fetch/s--IQPhTQnb--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg"
   }
-  
    
+}
    +

    @@ -262,14 +281,13 @@ Available JSON parameters 

    title: The title of an article (optional)
-  description: Description of the article (optional)
-  body_markdown: The Markdown body, with or without a front matter (required)
-  published: True if the article should be published right away, defaults to false (optional)
-  series: The name of the series the article should be published within (optional)
-  publish_under_org: True if the article should be placed under the organization belonging to the user creating the article, defaults to false (optional)
-  main_image: URL of the image to use as the cover (optional)
-  canonical_url: canonical URL of the article (optional)
-
    +description: Description of the article (optional) +body_markdown: The Markdown body, with or without a front matter (required) +published: True if the article should be published right away, defaults to false (optional) +series: The name of the series the article should be published within (optional) +publish_under_org: True if the article should be placed under the organization belonging to the user creating the article, defaults to false (optional) +main_image: URL of the image to use as the cover (optional) +canonical_url: canonical URL of the article (optional)

    @@ -277,25 +295,21 @@

    Unauthorized

    - 
    {
-    "error": "unauthorized",
-    "status": 401
-  }
-
    + 
    {
+  "error": "unauthorized",
+  "status": 401
+}

    Parameter validation error

    - - 
    {
    
-    "error": "Validation failed: Title can't be blank",
    
-    "status": 422
    
-  }
    
-
    + 
    {
+  "error": "Validation failed: Title can't be blank",
+  "status": 422
+}

    -
    -
    -
    - Rate limiting
    + + + Rate limiting

    There is a limit of 10 articles created each 30 seconds by the same user.