⏬ A middleman for APIs. Download, cache, get 100% uptime.
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.
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)
This is how you define an endpoint. This returns a function tied to a URL endpoint.
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)
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)
let endpoint = testApi.defineEndpoint("/users/:id", "GET");
endpoint({id: 1234, example: "yes"}); //sends a request to /users/1234?example=yes
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) {
...
}
You could also predefine api endpoints so that it is on the api object.
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)
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
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
Instead of defining each individual endpoint you can define a resource.
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
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.
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