REST API

Articles

HTTP Method	Description	Resource	Success Code	Failure Code
POST	Create an article	/<version>/articles	201	400, 403
GET	Retrieve all articles for a user	/<version>/users/<username>/articles	200	400
GET	Retrieve a specific article	/<version>/articles/<slug>	200	404

Create an Article

Request Body Parameters

Parameter	Type	Required
title	string	Yes
body	string	Yes
meta_description	string	Yes
featured_image	string	No

Request

curl -X POST \
https://api.talel.io/v1/articles \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"title": <str>, "body": <str>, "meta_description": <str>, "featured_image": <str>}'

Success Response

Response Body

201: CREATED

{
  "id" 1,
  "user_id": 1,
  "created_at": "1986-06-05T00:00:00.000000",
  "updated_at": "1986-06-05T00:00:00.000000" | null,
  "title": "Article Title",
  "slug": "article-title",
  "body": "# Article Body",
  "html": "<h1>Article Body</h1>",
  "table_of_contents": "<div><ul>...</ul></div>",
  "featured_image": "/s3/url/to/featured_image.jpg" | null,
  "meta_description": "Article description",
  "url": "https://www.talel.io/articles/article-title"
}

Error Response

400: BAD REQUEST

{
  "error": {
    "message": "Missing request body",
    "status": 400,
    "type": "Bad Request"
  }
}

400: BAD REQUEST

{
  "error": {
    "message": "Expected '<key>' key",
    "status": 400,
    "type": "Bad Request"
  }
}

403: FORBIDDEN

{
  "error": {
    "message": "No authorization header provided",
    "status": 403,
    "type": "Forbidden"
  }
}

403: FORBIDDEN

{
  "error": {
    "message": "No authorization token provided",
    "status": 403,
    "type": "Forbidden"
  }
}

403: FORBIDDEN

{
  "error": {
    "message": "<pyjwt_error>",
    "status": 403,
    "type": "Forbidden"
  }
}

Retrieve All Articles for a User

Query Parameters

Pagination: ?page=<number>&limit=<number>

Request

curl -X GET \
https://api.talel.io/v1/users/<username>/articles

Success Response

Link Header

URLs for the next and previous pagination values.

Link: </users/<username>/articles?page=3&limit=10>; rel="next", </users/<username>/articles?page=1&limit=10>; rel="prev"

X-Total-Count Header

Total number of articles for the queried user.

X-Total-Count: 100

Response Body

200: OK

{
  "user": {
    "username": "talel",
    "location": "berlin",
    "avatar_url": "/s3/url/to/avatar.jpg"
  },
  "articles": [
    {
      "id": 1,
      "created_at": "1986-06-05T00:00:00.000000",
      "updated_at": "1986-06-05T00:00:00.000000" | null,
      "title": "Article Title",
      "slug": "article-title",
      "body": "# Article Body",
      "html": "<h1>Article Body</h1>",
      "table_of_contents": "<div><ul>...</ul></div>",
      "featured_image": "/s3/url/to/featured_image.jpg" | null,
      "meta_description": "Article description",
      "url": "https://www.talel.io/articles/article-title"
    }
  ]
}

Error Response

400: BAD REQUEST

{
  "error": {
    "message": "Expected numeric query parameters",
    "status": 400,
    "type": "Bad Request"
  }
}

Retrieve a Specific Article

Request

curl -X GET \
https://api.talel.io/v1/articles/<slug>

Success Response

Response Body

200: OK

{
  "meta": {
    "adjacent_articles": {
      "next": {
        "title": "Next Article",
        "slug": "next-article"
      } | null,
      "prev": {
        "title": "Prev Article",
        "slug": "prev-article"
      } | null
    }
  },
  "article": {
    "id": 1,
    "created_at": "1986-06-05T00:00:00.000000",
    "updated_at": "1986-06-05T00:00:00.000000" | null,
    "title": "Article Title",
    "slug": "article-title",
    "body": "# Article Body",
    "html": "<h1>Article Body</h1>",
    "table_of_contents": "<div><ul>...</ul></div>",
    "featured_image": "/s3/url/to/featured_image.jpg" | null,
    "meta_description": "Article description",
    "url": "https://www.talel.io/articles/article-title"
  }
}

Error Response

404: NOT FOUND

{
  "error": {
    "message": "Article not found",
    "status": 404,
    "type": "Not Found"
  }
}

Assets

HTTP Method	Description	Resource	Success Code	Failure Code
POST	Upload images	/<version>/assets/images	200	400, 403

Upload Images

Request

curl -X POST \
https://api.talel.io/v1/assets/images \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: multipart/form-data" \
-F "<name>=<content>"

Success Response

Response Body

200: OK

{
  "image_objects_urls": ["https://s3.amazonaws.com/<bucket>/<user_id>/images/<image_file>"]
}

Error Response

400: BAD REQUEST

{
  "error": {
    "message": "One or more image files are of invalid type",
    "status": 400,
    "type": "Bad Request"
  }
}

400: BAD REQUEST

{
  "error": {
    "message": "One or more image files are too large",
    "status": 400,
    "type": "Bad Request"
  }
}

400: BAD REQUEST

{
  "error": {
    "message": "<aws_error>",
    "status": 400,
    "type": "Bad Request"
  }
}

403: FORBIDDEN

{
  "error": {
    "message": "No authorization header provided",
    "status": 403,
    "type": "Forbidden"
  }
}

403: FORBIDDEN

{
  "error": {
    "message": "No authorization token provided",
    "status": 403,
    "type": "Forbidden"
  }
}

403: FORBIDDEN

{
  "error": {
    "message": "<pyjwt_error>",
    "status": 403,
    "type": "Forbidden"
  }
}

Health

HTTP Method	Description	Resource	Success Code	Failure Code
GET	Check backend API health	/<version>/health	200

Check Backend API Health

Request

curl -X GET \
https://api.talel.io/v1/health

Success Response

Response Body

200: OK

👍🏼