Welcome to API-X! This guide will help you get up and running with API-X, a Node.js TypeScript package for building secure and scalable RESTful APIs quickly. API-X is built on top of Express and offers additional security and ease-of-use features, making it the perfect choice for secure API development.
Before you start, ensure you have the following installed:
To verify if you have Node.js and npm installed, run the following commands:
node -v
npm -v
If you prefer yarn, verify its installation with:
yarn -v
To install API-X in your project, run the following command:
npm install @evlt/apix
Or if you're using yarn:
yarn add @evlt/apix
This will install API-X along with all necessary dependencies.
Let's create a simple API to demonstrate how easy it is to use API-X.
First, create a new directory for your project and initialize it:
mkdir my-apix-api
cd my-apix-api
npm init -y
Next, add TypeScript support to your project:
npm install typescript --save-dev
npx tsc --init
Ensure you've installed all dependencies:
npm install --save-dev @evlt/apix express @types/express
Now, let's create a simple server using API-X. Create a new file named server.ts in your project root directory:
import {
ApiXManager,
ApiXMethod,
ApiXMethodCharacteristic,
ApiXDataManager,
ApiXAccessLevelEvaluator,
ApiXRedisStore,
ApiXConfig,
ApiXAccessLevel,
ApiXRequestInputSchema
} from '@evlt/apix';
import { Request } from 'express';
const helloWorldMethod: ApiXMethod = {
entity: 'hello',
method: 'world',
characteristics: new Set([ApiXMethodCharacteristic.PublicUnownedData]),
requestHandler: (req, res) => {
const data = {
success: true,
message: 'Hello, world!'
};
return { data }; // defaults to status 200. To change, set the `status` property.
// return { status: 200, data };
}
}
class DataManager implements ApiXDataManager {
getAppKeyForApiKey(apiKey: string): string | null {
/// single app has access
return apiKey === process.env.API_KEY ? process.env.APP_KEY! : null;
}
}
class AccessLevelEvaluator extends ApiXAccessLevelEvaluator {
// Can be used to implement additional methods such as `isAuthenticatedRequestor`
// when working with authentication.
}
const config = new ApiXConfig();
/// If using redis, use ApiX implementation. Otherwise you can implement
/// you own by implementing the `ApiXCache` interface.
const cache = new ApiXRedisStore(/* redis server, if not local */);
const manager = new ApiXManager(
new AccessLevelEvaluator(),
new DataManager(),
config,
cache,
console // during development, log to the console
);
/// Must only be used during development.
/// Disables some security features for easy testing
manager.developerModeEnabled = true;
manager.registerAppMethod(helloWorldMethod);
/// Run the server
manager.start();
In this example:
GET endpoint accessible at /hello/world.To compile and run your TypeScript project, add the following script to your package.json:
"scripts": {
"build": "tsc",
"start": "npm run build && node dist/server.js"
}
Compile your TypeScript code:
npm run build
Then start your server:
npm run start
Use curl or a similar tool to create a request:
curl -X GET "http://localhost:3000/hello/world" \
-H "Content-Type: application/json" \
-H "X-API-Key: <YOUR_API_KEY>" \
-H "X-Signature: AnySignature" \
-H "X-Signature-Nonce: AnyNonce" \
-H "Date: $(date -u +"%a, %d %b %Y %H:%M:%S GMT")"
Make sure to replace <YOUR_API_KEY> with the same key used in the server accessible via process.env.API_KEY.
Note that because developement mode is enabled, HTTPS is not required, and the X-Signature and X-Signature-Nonce headers are set to any arbitrary value and the request will still work.
And the response JSON should be:
{
"success": true,
"message": "Hello, world!"
}
_Note: you can also use API-X official Node.js client to implement a client for this sample server.
You’ve just created your first secure API using API-X! Here are some ideas for what you could do next:
Happy coding!