Articles API¶

Overview
List and Search articles

Overview ¶

An article in the knowledge base is composed of a title and an HTML content, and belongs to one or more categories.

For employees, the access to an article can be based on:

The organisation perimeter of the employee
Some filtering rules based on the custom attributes of the employee

For managers, the access to an article can be based on the role of the manager.

List and Search articles ¶

This method returns all articles based the query GET parameters.

URL ¶

GET /api/articles/?...
    Accept: application/json
    Content-Type: application/json
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Parameters ¶

Search filters:

Parameter	Description	Type	mandatory	Exemple
category_code	Identifying code (slug) of a category. If set, return only the articles included in this category.	`VARCHAR(50)`	`optional`	category_code: onboarding
accessible_by	Some articles may be accessible only to employees or managers. When set to `employees`, returns only the employee articles, when set to `managers`, returns only manager articles. If empty or not in the query, all articles are returned.	`ENUM`	`optional`, can be `employee`, `manager`	accessible_by: employees
employee_technical_id	Return only the articles accessible to this specific employee. Note: `accessible_by` should be either `employees` or empty. If empty or not in the query, all articles are returned.	`VARCHAR(50)`	`optional`	employee_technical_id: XAQ678900
manager_technical_id	Return only the articles accessible to this specific manager. Note: `accessible_by` should be either `managers` or empty. If empty or not in the query, all articles are returned.	`VARCHAR(50)`	`optional`	manager_technical_id: MAQ678900
featured	If true, returns only “featured” articles (those articles are displayed on the employee home page), if false, return non “featured” articles. If empty or not in the query, all articles are returned.	`BOOLEAN`	`optional`	featured: true
state	Returns only the articles with this specific state. If empty or not in the query, all articles are returned.	`ENUM`	`optional`, can be `published`, `draft`	state: published
query	Full text search in the article title and the article content.	`text`	`optional`	query: Onboarding form

Ordering and pagination:

Parameter	Description	Type	mandatory	Exemple
order_by	Ordering rule. Specify an attribute of an article, with a possible unary negative to imply descending sort order. The attribute can be `created_at`, `updated_at`, `title`, `total_hits`	`ATTRIBUTE`	`optional`	order_by: -created_at
per_page	Number of request per page (defaults to 20, max 100)	`INTEGER`	`optional`	per_page: 50
page	Page number	`INTEGER`	`optional` (defaults to 1)	page: 2

Response ¶

Success¶

The response is encoded in the JSON format with the following parameters, and is a list of article objects with the following attributes:

Parameter	Description	Type	Exemple
slug	The slug of the article, wich is the default unique identifier used in the URI for this article	`VARCHAR(255)`	how-to-complete-the-onboarding-form
title	The title of the article	`VARCHAR(255)`	How to complete the onboarding form ?
body	The HTML content of the article	`TEXT`	<div>…</div>
categories	The list of categories of this article	`LIST(JSON_OBJECT)`	[{…}, {…}]
featured	The featured state of the article	`BOOLEAN`	false
state	The state of the article (can be `published` or `draft`)	`ENUM`	published
total_hits	Total number of pageviews of this article on the employee portal (API hits are not counted…)	`INTEGER`	1856
updated_at	Last update of the article	`DATETIME`	2012-01-01T12:00:00+00:00
created_at	Creation date of the article	`DATETIME`	2012-01-01T12:00:00+00:00
manager_url	The URL of the `request` in Request Manager (needs manager authentication)	`URL`	https://xxxx.peopleask.com/…
employee_url	The URL of the `request` in Request Manager employee portal (needs employee authentication)	`URL`	https://xxxx.peopleask.com/…
api_url	The URI of the `request` (needs API authentication)	`URL`	https://xxxx.peopleask.com/…

For instance:

HTTP 200 OK:

HTTP/1.1 200 OK
Link: <https://BASE_URL/manager/articles/?page=2&per_page=30>; rel="next",
      <https://BASE_URL/manager/articles/?page=5&per_page=30>; rel="last"

[
  {article_object_1},
  ...,
  {article_object_2}
]

Where article_object_x is a json like this:

{
  "slug": "how-to-complete-the-onboarding-form",
  "title": "How to complete the onboarding form?",
  "body": "<div>...</div>",
  "categories": [
    {
      "slug": "onboarding",
      "name": "OnBoarding Section!",
      "language_code": "en",
      "description": "..."
    },
    {
      "slug": "accueil",
      "name": "Accueil dans l'entreprise !",
      "language_code": "fr",
      "description": "..."
    },
  ],
  "featured": false,
  "state": "published",
  "total_hits": 5678,
  "updated_at": "2012-01-01T12:00:00+00:00",
  "created_at": "2012-01-01T12:00:00+00:00",
  "api_url": "https://API_DOMAIN/api/articles/:slug/",
  "manager_url": "https://CLIENT-SUBDOMAIN/manager/articles/:slug/",
  "employee_url": "https://CLIENT-SUBDOMAIN/employee/articles/:slug/"
}

Errors¶

HTTP 400 Bad Request: Invalid parameters.

HTTP 403 Forbidden: Authentication failed.

Sample curl call ¶

curl -v -X GET "https://peopleask.net/api/articles/?category_code=onboarding&employee_technical_id=56789G79" \
    -H "Content-type: application/json" \
    -H "Accept: application/json" \
    -H "X-API-KEY: XXXXXXXXXXXXXX"

Articles API¶

Overview¶

List and Search articles¶

URL¶

Parameters¶

Response¶