PseudonameAPI is the backend API that serves the Pseudoname.io website.
To a larger extent, the PseudonameAPI can be viewed as a node.js wrapper for the ForwardMX API. By using this wrapper, Pseudoname is able to keep their API key secret and not exposed in the development console following each ForwardMX API call. Instead of allowing the user to directly access the ForwardMX API, the PseudonameAPI acts as an intermediary and applies additional validation, logging, and security checks to each user request.
Pseudoname.io is a free, disposable email alias generating service. Pseudoname is also open source and more information about it can be found here.
PseudonameAPI is very easy to install and launch.
- Download the latest release from the Releases Page.
- (Optional) If you haven't already, download and install node.js.
- Open your terminal of choice.
- Move into the project's directory via:
cd Downloads/PseudonameAPI- Install the dependency node modules by running the following command:
npm installNote: When prompted, you may need to provide administrator credentials to complete the installation.
- You will need to set an environment variable for your ForwardMX API Key. On a Mac, this is done via the following command (omit the
<>symbols):
export localForwardMxApiKey=<value>Note: If you make a mistake, you can reverse this action by running:
unset <localForwardMxApiKey>Once complete, verify that the API key has been set correctly by viewing your environment variables. Again, using a Mac as an example:
env- If correct, you may then start the server via:
node src/index.js- (Optional) Once the server is running, you can use Postman to craft requests, send requests, and view the server's responses.
Mocha/Chai unit tests have been provided within the /test/ directory. The test files mirror the application files, i.e /test/test.middlewares.js tests the functionality of the middlewares.js file. Run all the tests via:
npm testTravis CI is used for continuous integration, the project page can be viewed here. The badge listed above^ (which is also located at the top of this README document) displays the current build status. Each merge into master and each Pull Request is automatically tested and upon passing, is automatically deployed to heroku.
| Route: | HTTP Method: | Usage: | Requires Parameters?: | Is Rate-Limited?: |
|---|---|---|---|---|
/ |
GET | This route verifies connectivity, displays the API name, version, and a link to the API documentation (what you're reading now). | No | No |
/add/ |
POST | This route is used to create aliases. | Yes | Yes |
/delete/ |
DELETE | This route is used to delete aliases. | Yes | Yes |
When using a route that requires parameters, the following parameters must be included in the request. If these parameters are not provided, the request will be refused:
| Parameter Name (as it must be sent to the API): | Parameter Information: | Example Parameter Value: |
|---|---|---|
alias |
This is the desired email alias. The alias is the first few characters of an email, as in @<domain.com>. | myalias |
realEmail |
This is the real email address in which the emails destined to the aliases will be forwarded to. | [email protected] |
The table below contains the response values (JSON keys) associated with each successful API call:
| API Response Value Name: | Possible Values: | Usage: |
|---|---|---|
success |
TRUE or FALSE |
This response value indicates whether the requested operation was performed successfully. |
message |
Really anything. Each API call has a specific list of possible messages. | This response value provides other information that cannot be expressed in boolean logic. |
In an effort to keep the system running smoothly for all users, each IP address is only permitted to make 10 requests, per route, every 60 minutes.
Please see the routes table above for information as to which routes are rate-limited.
In order to make use of the PseudonameAPI, a paid ForwardMX account is required. This service, which is programmatically interacted with, manages users' email aliases and provides the email forwarding/liaison service.
PseudonameAPI utilizes the following open source libraries:
- Node.js — A Javascript-based, evented input/output framework for the backend.
- Express — A fast node.js network application framework.
- XMLHTTPRequest — A wrapper that emulates the web browser's native Javascript XMLHttpRequest object and functionalities.
- Mocha — A feature-rich JavaScript unit-testing framework.
- Chai — A BDD (Behavior-Driven Development) / TDD (Test-Driven-Development) assertion library for node.
- Chai-HTTP — A Chai plug-in that enables Chai assertions to integrate with HTTP operations.
- Helmet.js — A collection of security addons that can be toggled on/off together or in isolation.
- ESLint — A linter that helps to enforce code style, structure, and ECMAScript compliance.
"Thank you" to the developers and supporters of these projects, and all open source work for that matter. Without you, PseudonameAPI would not exist.
Please review the CONTRIBUTING.md document.
- Explore the possibility of encryption. — (This may require collaboration with ForwardMX)
You'll find information about each release below.
- Updated lodash dependency to address security concern (for more info, see lodash/lodash#4336)
- Added Helmet.js for security. (#8)
- Added rate-limiting. (#9)
- Updated the codebase to be ECMAScript 8 / ECMAScript 2017 compliant. (#10)
- Updated the API's HTTP methods (
/delete/is now a DELETE,/add/is now a POST). (#11)- Updated the methods allowed in the CORS middleware.
- Updated tests.
- Added the CONTRIBUTING.md file. (#12)
- Prevented the daisy-chaining of aliases. (#13)
- Added tests.
- Upgraded ES-Lint dependency per reports of security issues (#16)
- Fixed start script (#21)
- Changed ES-Lint rules (AirBnB laid a good foundation, but some of their requirements, namely forced destructuring, made the codebase less readable).
- Other small tweaks to logging.
- Updated documentation.
- Added a simple logging middleware for diagnostic purposes.
- Tweaked routes to have more uniform responses.
- Purged old API key.
- Added a CORS IP filtering middleware.
- Built
/,/add/, and/delete/routes. - Added parameter checking middleware.
- Added parameter validation middleware.
- Added internal versioning.
- Added Mocha/Chai unit tests.
- Added Travis CI support.
- Added API documentation in the README.