5daf869e56
Co-authored-by: Fernando Valverde <fernando@fdo.cr> Co-authored-by: Fernando Valverde <fernando@visualcosita.com>
483 lines
16 KiB
JSON
483 lines
16 KiB
JSON
{
|
|
"openapi": "3.0.3",
|
|
"info": {
|
|
"title": "Forem API V1",
|
|
"version": "v1",
|
|
"description": "Access Forem articles, users and other resources via API.\n For a real-world example of Forem in action, check out [DEV](https://www.dev.to).\n All endpoints require an 'api-key' header and a accept header.\n\n Dates and date times, unless otherwise specified, must be in\n the [RFC 3339](https://tools.ietf.org/html/rfc3339) format."
|
|
},
|
|
"paths": {
|
|
"/api/articles": {
|
|
"get": {
|
|
"summary": "Published articles",
|
|
"tags": ["articles"],
|
|
"description": "This endpoint allows the client to retrieve a list of articles.\n\n\"Articles\" are all the posts that users create on DEV that typically\nshow up in the feed. They can be a blog post, a discussion question,\na help thread etc. but is referred to as article within the code.\n\nBy default it will return featured, published articles ordered\nby descending popularity.\n\nIt supports pagination, each page will contain `30` articles by default.",
|
|
"operationId": "getArticles",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/pageParam"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/perPageParam30to1000"
|
|
},
|
|
{
|
|
"name": "tag",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Using this parameter will retrieve articles that contain the requested tag. Articles\nwill be ordered by descending popularity.This parameter can be used in conjuction with `top`.",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "discuss"
|
|
},
|
|
{
|
|
"name": "tags",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Using this parameter will retrieve articles with any of the comma-separated tags.\nArticles will be ordered by descending popularity.",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "javascript, css"
|
|
},
|
|
{
|
|
"name": "tags_exclude",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Using this parameter will retrieve articles that do _not_ contain _any_\nof comma-separated tags. Articles will be ordered by descending popularity.",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "node, java"
|
|
},
|
|
{
|
|
"name": "username",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Using this parameter will retrieve articles belonging\n to a User or Organization ordered by descending publication date.\n If `state=all` the number of items returned will be `1000` instead of the default `30`.\n This parameter can be used in conjuction with `state`.",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "ben"
|
|
},
|
|
{
|
|
"name": "state",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Using this parameter will allow the client to check which articles are fresh or rising.\n If `state=fresh` the server will return fresh articles.\n If `state=rising` the server will return rising articles.\n 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",
|
|
"required": false,
|
|
"description": "Using this parameter will allow the client to return the most popular articles\nin the last `N` days.\n`top` indicates the number of days since publication of the articles returned.\nThis param can be used in conjuction with `tag`.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"minimum": 1
|
|
},
|
|
"example": 2
|
|
},
|
|
{
|
|
"name": "collection_id",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Adding this will allow the client to return the list of articles\nbelonging 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": {
|
|
"example": [
|
|
{
|
|
"type_of": "article",
|
|
"id": 286,
|
|
"title": "Terrible Swift Sword1",
|
|
"description": "Cardigan taxidermy stumptown muggle magic. Tumblr lumbersexual yolo gluten-free taxidermy truffaut...",
|
|
"readable_publish_date": "Jul 6",
|
|
"slug": "terrible-swift-sword1-4gja",
|
|
"path": "/username1/terrible-swift-sword1-4gja",
|
|
"url": "http://localhost:3000/username1/terrible-swift-sword1-4gja",
|
|
"comments_count": 0,
|
|
"public_reactions_count": 0,
|
|
"collection_id": null,
|
|
"published_timestamp": "2022-07-06T16:49:01Z",
|
|
"positive_reactions_count": 0,
|
|
"cover_image": "http://localhost:3000/assets/12-f9d673ae4ff98002f782ab82c641f2f26673be728e8f5409bea83f2d1de15323.png",
|
|
"social_image": "http://localhost:3000/assets/12-f9d673ae4ff98002f782ab82c641f2f26673be728e8f5409bea83f2d1de15323.png",
|
|
"canonical_url": "http://localhost:3000/username1/terrible-swift-sword1-4gja",
|
|
"created_at": "2022-07-06T16:49:07Z",
|
|
"edited_at": null,
|
|
"crossposted_at": null,
|
|
"published_at": "2022-07-06T16:49:01Z",
|
|
"last_comment_at": "2022-07-06T16:49:01Z",
|
|
"reading_time_minutes": 1,
|
|
"tag_list": ["discuss"],
|
|
"tags": "discuss",
|
|
"user": {
|
|
"name": "Malorie \"Herman\" \\:/ Trantow",
|
|
"username": "username1",
|
|
"twitter_username": "twitter1",
|
|
"github_username": "github1",
|
|
"website_url": null,
|
|
"profile_image": "/uploads/user/profile_image/407/bcaaa39b-60d0-4dc2-97d2-9ec5c9e05b47.jpeg",
|
|
"profile_image_90": "/uploads/user/profile_image/407/bcaaa39b-60d0-4dc2-97d2-9ec5c9e05b47.jpeg"
|
|
},
|
|
"organization": {
|
|
"name": "Stamm Group",
|
|
"username": "org1",
|
|
"slug": "org1",
|
|
"profile_image": "/uploads/organization/profile_image/109/fb157fe5-9a66-4baf-91cb-216f0a206e5e.png",
|
|
"profile_image_90": "/uploads/organization/profile_image/109/fb157fe5-9a66-4baf-91cb-216f0a206e5e.png"
|
|
},
|
|
"flare_tag": {
|
|
"name": "discuss",
|
|
"bg_color_hex": "#000000",
|
|
"text_color_hex": "#ffffff"
|
|
}
|
|
}
|
|
],
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ArticleIndex"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"description": "unauthorized"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://dev.to/api",
|
|
"description": "Production server"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"api-key": []
|
|
}
|
|
],
|
|
"components": {
|
|
"securitySchemes": {
|
|
"api-key": {
|
|
"type": "apiKey",
|
|
"name": "api-key",
|
|
"in": "header",
|
|
"description": "API Key authentication.\n\nAuthentication for some endpoints, like write operations on the\nArticles API require a DEV API key.\n\nAll authenticated endpoints are CORS disabled, the API key is intended for non-browser scripts.\n\n### Getting an API key\n\nTo obtain one, please follow these steps:\n\n - visit https://dev.to/settings/extensions\n - in the \"DEV API Keys\" section create a new key by adding a\n description and clicking on \"Generate API Key\"\n\n \n\n - You'll see the newly generated key in the same view\n "
|
|
}
|
|
},
|
|
"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
|
|
}
|
|
},
|
|
"perPageParam30to100": {
|
|
"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": 100,
|
|
"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
|
|
}
|
|
},
|
|
"listingCategoryParam": {
|
|
"name": "category",
|
|
"in": "query",
|
|
"description": "Using this parameter will return listings belonging to the\n requested category.",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "cfp"
|
|
}
|
|
},
|
|
"schemas": {
|
|
"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"
|
|
}
|
|
}
|
|
},
|
|
"ArticleIndex": {
|
|
"description": "Resprentation of an article or post returned in a list",
|
|
"type": "object",
|
|
"properties": {
|
|
"type_of": {
|
|
"type": "string"
|
|
},
|
|
"id": {
|
|
"type": "integer",
|
|
"format": "int32"
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"cover_image": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"nullable": true
|
|
},
|
|
"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"
|
|
},
|
|
"positive_reactions_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",
|
|
"nullable": true
|
|
},
|
|
"crossposted_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true
|
|
},
|
|
"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"
|
|
},
|
|
"reading_time_minutes": {
|
|
"description": "Reading time, in minutes",
|
|
"type": "integer",
|
|
"format": "int32"
|
|
},
|
|
"user": {
|
|
"$ref": "#/components/schemas/SharedUser"
|
|
},
|
|
"flare_tag": {
|
|
"$ref": "#/components/schemas/ArticleFlareTag"
|
|
},
|
|
"organization": {
|
|
"$ref": "#/components/schemas/SharedOrganization"
|
|
}
|
|
},
|
|
"required": [
|
|
"type_of",
|
|
"id",
|
|
"title",
|
|
"description",
|
|
"cover_image",
|
|
"readable_publish_date",
|
|
"social_image",
|
|
"tag_list",
|
|
"tags",
|
|
"slug",
|
|
"path",
|
|
"url",
|
|
"canonical_url",
|
|
"comments_count",
|
|
"positive_reactions_count",
|
|
"public_reactions_count",
|
|
"created_at",
|
|
"edited_at",
|
|
"crossposted_at",
|
|
"published_at",
|
|
"last_comment_at",
|
|
"published_timestamp",
|
|
"user",
|
|
"reading_time_minutes"
|
|
]
|
|
},
|
|
"SharedUser": {
|
|
"description": "The resource creator",
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"username": {
|
|
"type": "string"
|
|
},
|
|
"twitter_username": {
|
|
"type": "string",
|
|
"nullable": true
|
|
},
|
|
"github_username": {
|
|
"type": "string",
|
|
"nullable": true
|
|
},
|
|
"website_url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"nullable": true
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|