Sourcefabric Manuals

 English |  Español |  Français |  Italiano |  Português |  Русский |  Shqip

Template library

Introduction to Newscoop API

Newscoop REST API is a basic REST API for Newscoop, which in its first version will allow you to only fetch content. Further on you will be able to give something back to Gimme by pushing data via write services.

For better understanding of what Gimme API is you can have a look at this FAQ.

Methods overview

We use HTTP methods to operate on these resources or collections of resources.

Method

Collection

Resource

GET

fetch resources

fetch resource

POST

create a resource in this collection

 

PUT

 

create or update a resource here

PATCH

 

update part of a resource

DELETE

 

delete a resource

 

Endpoints and Versions

example.com/api/

API endpoints don't have version mark in main endpoint uri, but for special reasons it can be allowed - ex. for debugging, or removing old API functions. 

  • example.com/api/articles
  • example.com/api/v3/articles => example.com/api/articles

If API is no longer supported, then we redirect user to current API version with Location HTTP header (30x HTTP status codes that indicate redirection - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3).

Pagination and sorting of collections

Default number of results on the page is 10.

Allowed parameters:

Parameter name

value

Description

page

integer

results page number

sort

array

array of sort directions indexed by column name e.g. sort[name]=asc

items_per_page

integer

override number of results in the response

GET /articles?page={integer}&sort={array}&items_per_page={integer}

If response does not contain all of the result resources, we append to the response special pagination object:

Pagination

"pagination": {
  "itemsPerPage": {integer},
  "currentPage": {integer},
  "nextPageLink": {string}, // /articles/?page=2
  "previousPageLink": {string}, // /articles/?page=1
  "itemsCount": {integer}
}

Partial response

If client doesn't want whole response object, then he can choose particular fields:

GET /articles?fields=title,date,number

Parameter name

value

Description

fields

string

Comma separated list of properties of requested objects.

Null values in response

Keys with null value will be removed from response.

Response format

We use the Accept and Content-Type headers to agree what formats to use. But for now we support only application/json. 

Response codes

Code

Message

Description

200

OK

Success!

304

Not Modified

There was no new data to return.

400

Bad Request

The request was invalid. An accompanying error message will explain why. This is the status code will be returned during rate limiting.

401

Unauthorized

Authentication credentials were missing or incorrect.

403

Forbidden

The request is understood, but it has been refused. An accompanying error message will explain why. This code is used when requests are being denied due to update limits.

404

Not Found

The URI requested is invalid or the resource requested, such as a user, does not exists.

500

Internal Server Error

Something is broken.

502

Bad Gateway

API is down or being upgraded.

503

Service Unavailable

API servers are up, but overloaded with requests. Try again later.

504

Gateway timeout

The API servers are up, but the request couldn't be serviced due to some failure within our stack. Try again later.

Error response

{
  "errors":[
    {
      "message":"Something is broken.",
      "code":500
    }
  ]
}

There has been error in communication with Booktype server. Not sure right now where is the problem.

You should refresh this page.