Skip to content

DOCS.md

Latest commit

 

History

History
678 lines (487 loc) · 15.8 KB

DOCS.md

File metadata and controls

678 lines (487 loc) · 15.8 KB

RESTfulNews API v0.1.4

Open source news API for quants.

Auth

Basic Authentication

All requests to our API require authentication. The Bearer token must be provided as part of header for every request, using the authorisation Bearer variable. This token is retrieved after a successful login with an e-mail and password using Basic Authentication.

POST /auth/basic

Parameters

Name Type Description
email String

User's Email address
password String

User's password

Examples

Curl Usage:

curl http://api.restfulnews.com/auth -XPOST \
-H 'Content-Type:application/json' \
-d '{"email":"<email>","password":"<password>"}' \

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "token":"<bearer token>",
 "user": {
   "id":"<user_id token>",
   "name":"<name>",
   "picture":"<display picture link>",
   "role":"<role>",
   "email":"<email>",
   "createdAt":"<created at date>"
 }
}

Authenticate with Google

All requests to our API require authentication. The Bearer token must be provided as part of header for every request, using the authorisation Bearer variable. This token is retrieved after a successful login with using Google Authentication.

POST /auth/google

Headers

Name Type Description
Bearer String

Google user accessToken.

Examples

Curl Usage:

curl http://api.restfulnews.com/auth -XPOST \
-H 'Content-Type:application/json' \
-d '{"token":"<Google OAuth Token>"}' \
--oauth2-bearer "<bearer token>"

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "token":"<bearer token>",
 "user": {
     "id":"<user_id token>",
     "name":"<name>",
     "picture":"<display picture link>",
     "role":"<role>",
     "email":"<email>",
     "createdAt":"<created at date>"
 }
}

News

Create News

Creates a News object.

POST /news

Headers

Name Type Description
Bearer String

user access token.

Parameters

Name Type Description
title String

Title of the news article.
abstract String

Abstract of the news article.
url String optional

URL to the news article.
source String optional

URL Source to the news article.
thumbnail String optional

URL Source to the news article thumbnail.
publishedAt Date.toISOString optional

Pulished date of the news article. (format: YYYY-MM-DDTHH:mm:ss.sssZ)

Examples

Curl Usage:

curl --request POST \
--url http://api.restfulnews.com/news \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json' \
--data '{"title": "<title>", "publishedAt": "<published at date>", \
 "fingerprint": "<fingerprint id>", "url": "<url>", "abstract": "<abstract>", \
 "thumbnail": "<thumbnail link>", "source": "<source>"}'

{
 "id": "<news article id>",
 "createdAt": "<created at date>",
 "updatedAt": "<updated at date>",
 "url": "<url>",
 "title": "<title>",
 "source": "<source>",
 "abstract": "<abstract>",
 "thumbnail": "<thumbnail link>"
}

Delete News

Deletes an existing News object.

DELETE /news/:id

Headers

Name Type Description
Bearer String

admin access token.

Examples

Curl Usage:

curl --request DELETE \
--url http://api.restfulnews.com/news/<news article id> \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json'

Retrieve news

Retrieves a list of News objects.

GET /news

Headers

Name Type Description
Bearer String

admin access token.

Parameters

Name Type Description
q String optional

Query to search.
page Number optional

Page number.
limit Number optional

Amount of returned items.
sort String[] optional

Order of returned items.
fields String[] optional

Fields to be returned.

Examples

Curl Usage:

curl --request GET \
--url http://api.restfulnews.com/news \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json'

[
 {
  "id": "<news article id>",
  "createdAt": "<created at date>",
  "updatedAt": "<updated at date>",
  "url": "<url>",
  "title": "<title>",
  "source": "<source>",
  "abstract": "<abstract>",
  "thumbnail": "<thumbnail link>"
 },
 ...
]

Update News

Updates an existing News object with new information.

PUT /news/:id

Headers

Name Type Description
Bearer String

user access token.

Parameters

Name Type Description
title String

Title of the news article.
abstract String

Abstract of the news article.
url String optional

URL to the news article.
source String optional

URL Source to the news article.
thumbnail String optional

URL Source to the news article thumbnail.

Examples

Curl Usage:

curl --request PUT \
--url http://api.restfulnews.com/news/<news article id> \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json' \
--data '{"title":"<title>", "url":"<url", "source":"<source>", \
"abstract":"<abstract>", "thumbnail":"<thumbnail>"}'

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "id": "<news article id>",
 "createdAt": "<created at date>",
 "updatedAt": "<updated at date>",
 "url": "<url>",
 "title": "<title>",
 "source": "<source>",
 "abstract": "<abstract>",
 "thumbnail": "<thumbnail link>"
}

Search

Search for news articles (main)

Search for news articles from our news sources based which can be filtered by Topic, Company, Pulished Date.

GET /search

Headers

Name Type Description
Bearer String

user access token.

Parameters

Name Type Description
topics String

News topics split separated by a comma(,).
companyids String

List of company id's separated by a comma(,).
start_date Date.toISOString optional

Pulished date interval start. (format: YYYY-MM-DDTHH:mm:ss.sssZ)
end_date Date.toISOString optional

Pulished date interval end. (format: YYYY-MM-DDTHH:mm:ss.sssZ)
limit Integer optional

Maximum news articles to display per page.
page Integer optional

Page number of results.

Examples

Curl Usage:

curl --request GET \
--url http://api.restfulnews.com/search?topics=<topics>&start_date=<iso_time>&end_date=<iso_time>&companyids=<list of company id's> \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json' \

[
{
 "title": "<title>",
 "publishedAt": "<published at date>",
 "fingerprint": "<fingerprint id>",
 "url": "<url>",
 "abstract": "<abstract>",
 "thumbnail": "<thumbnail>",
 "source": "<source>"
},
...
}
]

Note: the `fingerprint` property is used to distinguish news articles, and is
generated from a hash of the news content.

User

Create user

Creates a user with the information provided in the parameters.

POST /users

Parameters

Name Type Description
email String

User's email.
password String

User's password.
name String

User's name.
picture String optional

User's picture.
role String optional

User's role.

Examples

Curl Usage:

curl --request POST --url http://api.restfulnews.com/users \
--header 'content-type: application/json' \
--data '{ "email": "<email>", "password": "<password>", \
"name": "<name>", "picture": "<picture link>"}'

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "token": <"bearer token">,
 "user":
 {
   "id": "<user id>",
   "name": "<name>",
   "picture": "<picture link>",
   "role": "<role>",
   "email": "<email>",
   "createdAt" : "<created at date>"
 }
}

Delete user

Deletes an existing user with the specified User ID.

DELETE /users/:id

Headers

Name Type Description
Bearer String

User access_token.

Examples

Curl Usage:

curl --request DELETE \
--url 'http://api.restfulnews.com/users/<user_id>' \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json'

Test if user exists

Checks if a user exists with the specified email.

POST /email/:email

Examples

Curl Usage:

curl --request POST \
--url http://api.restfulnews.com/users/<email> \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json'

Retrieve current user

Gets the current user who is logged in.

GET /users/me

Headers

Name Type Description
Bearer String

User access_token.

Examples

Curl Usage:

curl --request GET \
--url http://api.restfulnews.com/users/me \
--header 'authorization: Bearer <Bearer Token>' \
--header 'content-type: application/json'

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "id":"<user id>",
 "name":"<name>",
 "picture":"<picture link>",
 "role":"<role>",
 "email":"<email>",
 "createdAt":"<created at date>"
}

Retrieve user

Retrieves a user's data when given the User ID.

GET /users/:id

Examples

Curl Usage:

curl --request GET --url http://api.restfulnews.com/users/<user id> \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json'

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "id": "<user id>",
 "name": "<name>",
 "picture": "<picture link>",
 "role": "<role>"
}

Retrieve users

Gets a list of all users.

GET /users

Headers

Name Type Description
Bearer String

User access_token.

Parameters

Name Type Description
q String optional

Query to search.
page Number optional

Page number.
limit Number optional

Amount of returned items.
sort String[] optional

Order of returned items.
fields String[] optional

Fields to be returned.

Examples

Curl Usage:

curl --request GET \
--url http://api.restfulnews.com/users \
--header 'authorization: Bearer <bearer token>' \
--header 'content-type: application/json'

Success Response

Success-Response:

HTTP/1.1 200 OK

[
 {
   "id": "<user id>",
   "name": "<name>",
   "picture": "<picture>",
   "role": "<role>",
   "email": "<email>",
   "createdAt": "<created at date>"
 },
 ...
]

Send email

Sends a password reset code to the specified E-mail address.

GET /users/reset-code

Parameters

Name Type Description
email Object

Email address to receive the password reset token.

Update password

Updates an existing User's password.

PUT /users/:id/password

Headers

Name Type Description
Authorization String

Basic authorization with email and password.

Parameters

Name Type Description
password String

User's new password.

Examples

Curl Usage:

curl --request PUT \
 --url http://api.restfulnews.com/users/<user_id>/password \
 --header 'authorization: Bearer <Bearer Token>' \
 --header 'content-type: application/json' \
 --data '{"password":"<new password>}'

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "id": "<user id>",
 "name": "<name>",
 "picture": "<picture link>",
 "role": "<role>",
 "email": "<email>",
 "createdAt": "<created at date>"
}

Send email

POST /users/password/

Parameters

Name Type Description
email String

Email address
code String

Code

Update user

Updates an existing User's information based on the parameters entered.

PUT /users/:id

Headers

Name Type Description
Bearer String

User access_token.

Parameters

Name Type Description
name String optional

User's name.
picture String optional

User's picture.

Examples

Curl Usage:

curl --request PUT \
 --url http://api.restfulnews.com/users/<user_id>/update \
 --header 'authorization: Bearer <Bearer Token>' \
 --header 'content-type: application/json' \
 --data '{"name": "<name>", "picture": "<picture link>"}'

Success Response

Success-Response:

HTTP/1.1 200 OK

{
 "id": "<user id>",
 "name": "<name>",
 "picture": "<picture link>",
 "role": "<role>",
 "email": "<email>",
 "createdAt": "<created at date>"
}