Articles

Articles are central to MotorPress and we provide a number of methods for fetching and dealing with articles through the API.

The Article Object

This collection of endpoints deal with articles and will always return data in the same format. We provide a JSON Schema for the article object, which you can find here. You can use that schema to validate the JSON structure of any returned article data.

The following basic details are always included the article object, whether fetching a list of articles or a single article:

{
  "id": "7eefb9ce...",                          // The unique UUID of the article
  "organisation_id": "1c862f0a...",             // The UUID of the organisation that owns the article
  "title": "Article title",                     // The article's title
  "slug": "article-slug",                       // The article's URL slug
  "synopsis": "Article synopsis...",            // A short introduction to the article content
  "published_at": "2022-01-20T00:00:00+00:00",  // The date and time the article was published
  "created_at": "2022-01-20T00:00:00+00:00"     // The date abd time the article was created
  "category": {
    "id": "b53b0c04...",                        // The UUID of the category the article is in
    "title": "Category title",                  // The title of the article's category 
  },
  "tags": [                                     // An array of tags that may be attached
    "tag-1",
    "tag-2",
  ],
  "links": {
    "view": "https://...",                      // Web link for this article
    "thumbnail": {                              // Thumbnails in different orientations
      "square": "http://...",
      "portrait": "http://...",
      "landscape": "http://..."
    }
  },
  "attachments": {                              // The number of attachments attached to the article
    "images": 0,
    "videos": 0,
    "documents": 0,
    "audio": 0,
  }
}

Fetch Articles

OrganisationMedia

You can retrieve the latest articles ordered by the publication date. Only published articles are included and there are no facilities available to fetch articles that have not been published to the MotorPress platform.

It is possible to filter the returned articles using the provided URL query parameters. For exmaple, you can pass a category slug or ID to the category parameters to only show articles that are in the specified categories.

This endpoint will always return a paginated response.

Endpoint

get

/articles

URL Parameters

A number of URL parameters are accepted which can be used to filter the returned articles. Note that month cannot be used if a year is not also specified. The category parameter accepts either a category slug or UUID.

Parameter	Description
year	Only include articles published in the specified year.
month	Only include articles published in the specified month. Requires that a year is specified.
category	The UUID or slug of a category. You can only specify one category at a time.
tags	Comma separated list of tags to filter articles by. You can specify any number of tags.

Example

curl "https://api.motorpress.co.za/articles?category=model-announcements" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer TEST_TOKEN'

<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.motorpress.co.za/articles?category=model-announcements');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Accept: application/json',
  'Content-Type: application/json',
  'Authorization: Bearer TEST_TOKEN',
]);

$response = curl_exec($ch);

if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

curl_close($ch);

{
  "data": [
    {
      "id": "c224bfbd-dd6b-423e-83aa-dba525f81600",
      "organisation_id": "1c862f0a-6a3d-446d-bfdc-fe76870dc1ca",
      "title": "Provident Dolorum",
      "slug": "provident-dolorum",
      "category": {
        "id": null,
        "title": "Motorsport"
      },
      "tags": [
        "expedita-labore-in",
        "sunt-rerum-minima"
      ],
      "synopsis": "Quia itaque optio hic dolores atque temporibus. Ut illum quos deserunt atque nesciunt sit. Neque doloribus hic et rerum maiores numquam ut beatae.",
      "rating": {
        "average": 0,
        "count": 0
      },
      "links": {
        "view": "https://motorpress.co.za/articles/provident-dolorum",
        "thumbnail": "https://motorpress.co.za/storage/defaults/thumbnail.jpg"
      },
      "attachments": {
        "images": 15,
        "videos": 1,
        "documents": 2,
        "audio": 0
      },
      "published_at": "2024-02-13T14:19:43.000000Z",
      "created_at": "2024-02-13T14:19:43.000000Z"
    },

    // ...
  ],
  "links": {
    "first": "https://api.motorpress.co.za/articles?page=1",
    "last": "https://api.motorpress.co.za/articles?page=2",
    "prev": null,
    "next": "https://api.motorpress.co.za/articles?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://api.motorpress.co.za/articles?page=1",
        "label": "1",
        "active": true
      },

      // ...
    ],
    "path": "https://api.motorpress.co.za/articles",
    "per_page": 20,
    "to": 20,
    "total": 36
  }
}

Fetch a Single Article

OrganisationMedia

The paginated articles endpoint returns a good amount of detail for each article but does not include the actual article body. Once an article has been selected you'll need to fetch that single article by it's ID to get the article's body. This endpoint returns a single article object.

Endpoint

get

/articles/[ARTICLE_ID]

Example

curl "https://api.motorpress.co.za/articles/7eefb9ce-8633-4aaf-a24a-7a9f4e7c6c41" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer TEST_TOKEN'

<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.motorpress.co.za/articles/7eefb9ce-8633-4aaf-a24a-7a9f4e7c6c41');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Accept: application/json',
  'Content-Type: application/json',
  'Authorization: Bearer TEST_TOKEN',
]);

$response = curl_exec($ch);

if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

curl_close($ch);

{
  "data": {
    "id": "7eefb9ce-8633-4aaf-a24a-7a9f4e7c6c41",
    "organisation_id": "1c862f0a-6a3d-446d-bfdc-fe76870dc1ca",
    "title": "Aut Tenetur Voluptas",
    "slug": "aut-tenetur-voluptas",
    "category": {
      "id": "b53b0c04-5c33-4998-bb69-6137d6f782bf",
      "title": "Model Announcements"
    },
    "tags": [
      "expedita-labore-in",
      "sunt-rerum-minima"
    ],
    "links": {
      "view": "https:\/\/motorpress.co.za\/articles\/aut-tenetur-voluptas",
      "thumbnail": {
        "square": "https:\/\/motorpress.co.za\/storage\/defaults\/thumbnail.jpg"
      }
    },
    "attachments": {
      "images": 16,
      "videos": 0,
      "documents": 3,
      "audio": 0
    },
    "published_at": "2024-01-20T18:19:43+00:00",
    "created_at": "2024-01-20T18:19:43+00:00"
  }

See Also

• Paginated Responses

• Categories

• PHP Client

  Article Attachments

Article can carry any number of attachments. Images, videos, documents and audio files can be attached to articles. When fetching articles, only the number of attachments are included in the returned article object. Since articles can have lots of attachments, they are not included when fetching paginated articles, or when fetching a single article.

Instead you can fetch article attachments by making requests to the separate attachment endpoints for this article. This means you only need to fetch the attachments you actually need. There is no need to include video attachments if you don't need them or there aren't any. You can use the attachment counts in the article object to determine which attachments you might want to fetch.

Images

OrganisationMedia

You can use this endponit to fetch a paginated list of images attached to the article. The response from this endpoint is the same as fetching an index of images.

Endpoint

get

/articles/{article_uuid}/images

See Also

• Image Object
• Fetching Images

Videos

OrganisationMedia

You can use this endponit to fetch a paginated list of videos attached to the article. The response from this endpoint is the same as fetching an index of videos.

Endpoint

get

/articles/{article_uuid}/videos

See Also

• Video Object
• Fetching Videos

Documents

OrganisationMedia

You can use this endponit to fetch a paginated list of documents attached to the article. The response from this endpoint is the same as fetching an index of documents.

Endpoint

get

/articles/{article_uuid}/documents

See Also

• Document Object
• Fetching Documents

Audio

OrganisationMedia

You can use this endponit to fetch a paginated list of audio files attached to the article. The response from this endpoint is the same as fetching an index of audio files.

Endpoint

get

/articles/{article_uuid}/audio

See Also

• Audio Object
• Fetching Audio