apidown

⏬ A middleman for APIs. Download, cache, get 100% uptime.

History

This application is beginner-friendly, and made for Hacktoberfest 2017, and should serve as a starting point for javascript open-source developers.

If you would like to contribute, follow Contributing.md.

Documentation

You can register an api with the following commands:

const api = require('apimust');
const testapi = api.url('www.sample-api.com') //Root url of the api
testapi
    .withPassword('CLEAN_TEXT_PASSWORD') //Add password auth
    .withHeaders({ 'User-Agent': 'mozilla' }) //Custom http headers

Then, you can use apimust to fetch data from the server, and automatically cache data in the process.

//Fetches the body of www.sample-api.com/users, and saves the data in the cache.
testapi.fetch('/users', function(err, result) {
    if(err) console.log(err);
    if(result) console.log(result);
})

//Using fetch on the same endpoint will fetch from cache now, and load much faster on slow connections.
testapi.fetch('/users', function(err, result) {
    if(err) console.log(err);
    if(result) console.log(result);
})

You can also integrate options into the fetch method:

const options = {
    preferOnline: true //Will try to fetch online first, and resort to cache as a fallback
    headers: {
        'User-Agent': 'mozilla' //Will add custom headers
    }
}

testapi.fetch('/users', function(err, result) {
    if(err) console.log(err);
    if(result) console.log(result);
}, options)

defineEndpoint

This is how you define an endpoint. This returns a function tied to a URL endpoint.

parameters

These are the parameters this takes 1. url the Url for the endpoint 2. method the method for the endpoint ("GET", "POST", "PUT", "DELETE" or "PATCH") 3. headers the headers for the endpoint (optional) 4. config the config for this endpoint (optional)

Return

This returns a function that sends a request to the endpoint. This function takes the following parameters: 1. payload this is the payload for the request (This is also used for formating the url) 2. headers the headers for this request (optional) 3. config The config for this request (optional)

Example

let endpoint = testApi.defineEndpoint("/users/:id", "GET");
endpoint({id: 1234, example: "yes"}); //sends a request to /users/1234?example=yes

Misc

These return promises so you can use async/await. You handle a response like so:

testApi.all_users().then((response) => {
    ...
}).catch(e => {
    ...
});

or

try {
    let response = await testApi.all_users();
    ...
}
catch(e) {
    ...
}

Predefined endpoint functions (get, post, delete, update)

You could also predefine api endpoints so that it is on the api object.

parameters

These are the parameters this takes 1. name the name of the method 2. url the Url for the endpoint 3. method the method for the endpoint ("GET", "POST", "PUT", "DELETE" or "PATCH") 4. headers the headers for the endpoint (optional) 5. config the config for this endpoint (optional)

Return

This returns the API object with new methods that corresponds to the name you gave it. this method takes all of the same parameters as defineEndpoint

Example

testApi.get("all_users", "/users");
    .post("create_user", "/users");
    .get("single_user", "/users/:id");
    .update("update_user", "/users/:id");
    .delete("delete_user", "/users/:id");

This will give you methods that you can use as a short cut like so:

testApi.all_users(); //Sends a GET request to /users
testApi.create_user({...}); //Sends a POST request to /users
testApi.single_user({id: 1234}); //sends a GET request to /users/1234

Resources

Instead of defining each individual endpoint you can define a resource.

Parameters

This takes the following parameters: 1. name the name of the resource. this could also be the base url 2. methods the methods this resource supports. (optional) defualts to ["GET", POST", "PUT", "DELETE"] 3. headers the headers for this resource 4. config the config for this resource 5. base_url the base_url for this resource, defaults to name 6. key the key for the resource. Defaults to to id This is what if formated on the base_url. For example if base_url is /users and key is id then the resulting url for unique requests would be /users/:id

Returns

This returns an object that has methods that sends out requests. These methods are find, all, delete, create, and update and are the same as described in the Predefined endpoint functions section.

Example

testApi.resource("users");

This creates five methods on a users object on testApi: find, all, delete, create, and update. For example:

testApi.users.all(); //sends a GET request to /users
testApi.users.find({id: 1234}); //sends a GET request to /users/1234
testApi.users.create({...}); //sends a POST request to /users
testApi.users.delete({id: 1234}) //sends a DELETE request to /users/1234
testApi.users.update({id: 1234, ...}) //sends a PUT/PATCH request to /users/1234