Articles API

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"