ALIS API Node.js Client
ALIS API made simple with syntax sugar
The simplest call looks like this.
const alis = alisarticles
The same call promisified, simply insert .p
after alis
.
// with the promise-based calls, you are free from callback hellalisparticles
Another example to get all the articles an authenticated user has published on ALIS with a promisified call. It loops through all the articles successively paginating till it reaches the end, but you can put some logics between each call with a getAll/getAllSync
function defined to make pagination easier.
This time the example uses an async/await
wrapper function to make it work like a synchronous code.
{ // Amazon Cognito authentication is handled in the background // the first argument for the API parameters to pass to the HTTPS request // the second argument for anything else specific to this library await alispmearticles // async/await functions execute line by line from top to bottom console}
Table of contents
- Installation
- Available Calls
- Authentication
- Syntax Sugar
- More Examples
- OAuth
- Tests
- Links
- Contributors
Installation
Use NPM.
npm i -s alis
Available Calls
Refer to the official ALIS API documentation located here.
All you have to do to make a call is to replace the slashes
with dots
and remove {}
from each pathname of the call. Also specify the request method in the second argument when it's not GET
.
When authentication is needed, pass your username
and password
to the second argument as well.
Arguments are
1st
parameters specified in the API document to pass to the API call.
2nd
anything else specific to this library
3rd
the last callback function (not for promise-based calls)
You can omit the first and second argument when not required and put the last callback function as the first argument. However, you cannot omit the first argument when you need to specify the second argument.
Some examples.
[GET] /articles/{article_id}
alisarticles
[POST] /me/articles/{article_id}/like
alismearticlesarticle_id
Note that some POST
and PUT
API calls don't return anything back when successful, in that case this library returns {statusCode: 200}
to indicate a successful operation.
Authentication
ALIS uses Amazon Cognito to authenticate users but this library handles that in the background for you. You just need to pass your username
and password
, then it authenticates you through the complicated process and stores the tokens in a temporary file, it automagically refreshes your tokens when they are expired.
There are 3 ways to make API calls with authentication.
- pass
username
andpassword
alisme
- directly pass
id_token
obtained by authentication (optionally withusername
)
alisme
- pass
refresh_token
andusername
(for some weired reasons)
alisme
Note that it's a good idea to always pass your username
since both authenticating and refreshing operations require username
to be done automatically.
Syntax Sugar
Manually paginating through articles and comments might be pain in the ass, so this library made it simpler for you.
You can specify a getAll
function to the second argument to make the call automatically go to the next page till it reaches the end. Use next
and stop
functions given back to you inside the getAll
function to navigate.
Do something asynchronous and call next
to get the next page or stop
to intercept the loop and finish the operation with the last callback function.
The forth object returned to you contains some useful information for pagination such as startNth
, endNth
, itemCount
, isNext
. startNth
and endNth
are not zero-based index but they count from 1 like ordinal numbers.
let page = 0alisarticles
The promise based calls with async/await
functions make it even simpler to fetch through articles. When you don't need asynchronous logic in the getAll
function, use getAllSync
instead so you don't have to even call next()
to get the next page. Simply return true
from getAllSync
function if you want to intercept the calls before the end.
{ let page = 0 await alisparticles // No need to specify the last callback function // things go line by line from top to bottom with async/await and promise console}
More Examples
To change your profile image.
const fs = const alis = const icon_path = `xxxxx.jpg`// the image should be base64 encodedconst icon_base64 = fs // don't forget the content-type, it's a required parameteralismeinfo // Of course you have the simpler promise version too// alis.p.me.info.icon(...)
To get all the articles and likes of an arbitrary user to calculate the total number of likes.
const alis = { let articles = await alispusersuser_idarticles console; let total_likes = 0 forlet article of articles let likes = await alisparticlesarticle_id console total_likes += likescount console}
To tip someone on an article.
const alis = // this is for 10 ALIS, so 1 ALIS = 1000000000000000000alismewallet
To get supporters on an article.
const alis = alisarticlesarticle_id
To reply to a comment.
const alis = alismearticlesarticle_idcomments
To report a fraud.
const alis = // possible reasons: anything_contrary_to_public_order|nuisance|copyright_violation|slander|illegal_token_usage|illegal_act|other// origin_url is required only with copyright_violationalismearticlesarticle_id
To get recommended articles.
const alis = alisarticles
Oauth 2.0
You can make a API call with OAuth 2.0 by simply adding oauth
after alis
. To authorize users, access_token
is required in the second argument. When refreshing the expired access_token
, it uses refresh_token
with client_id
and client_secret
; hence these parameters are required in the second argument as well. Unlike the Cognito authorization access_token
is not cached. You can update access_token
by using updated_access_token
in the returned object.
Call with a callback function may look like:
const alis = options = access_token: "<ACCESS_TOKEN>" refresh_token: "<REFRESH_TOKEN>" client_id: "<CLIENT_ID_OF_YOUR_APP" client_secret: "<CLIENT_SECRET_OF_YOUR_APP>" scope: "read" // optional (read/write) let page = 0alisoautharticles
Async/await call may look like:
const alis = options = access_token: "<ACCESS_TOKEN>" refresh_token: "<REFRESH_TOKEN>" client_id: "<CLIENT_ID_OF_YOUR_APP" client_secret: "<CLIENT_SECRET_OF_YOUR_APP>" scope: "read" // optional (read/write) { let articles = await alisoauthpusersuser_idarticles console; let total_likes = 0 forlet article of articles let likes = await alisoauthparticlesarticle_id console total_likes += likescount console}
Tests
Tests are to be written soon.