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 fast 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 {
AppManager,
EndpointMethod,
MethodCharacteristic,
DataManager,
AccessLevelEvaluator,
RedisStore,
ApiXConfig,
AccessLevel,
RequestInputSchema,
Request,
Response,
EndpointGenerator,
Route,
PublicResource
} from '@evlt/apix';
import {
Request as ExpressRequest,
Response as ExpressResponse
} from 'express';
/**
* Declarative endpoint definition. Makes it easier to define multiple endpoint
* under the same entity (e.g. all user methods under a single class, and with
* object instance lifecycles for resources.)
*/
@EndpointGenerator('hello')
class HelloWorld {
@Route('world')
@PublicResource()
public helloWorld(req: Request, res: ExpressResponse): Response {
const data = {
success: true,
message: 'Hello, world!'
};
return { data }; // defaults to status 200. To change, set the `status` property.
// return { status: 200, data };
}
}
/// Non-declarative method definition - Only use for single method or legacy pre-TS v5.
const helloWorldMethod: EndpointMethod = {
entity: 'hello',
method: 'world',
characteristics: new Set([MethodCharacteristic.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 MyDataManager implements DataManager {
getAppKeyForApiKey(apiKey: string): string | null {
/// single app has access
return apiKey === process.env.API_KEY ? process.env.APP_KEY! : null;
}
}
class MyAccessLevelEvaluator extends AccessLevelEvaluator {
// Can be used to implement additional methods such as `isAuthenticatedRequestor`
// when working with authentication.
}
const config = new ApiXConfig();
/// If using Redis, use the provided RedisStore. Otherwise implement
/// your own by implementing the `Cache` interface.
const cache = new RedisStore(/* redis server, if not local */);
const manager = new AppManager(
new MyAccessLevelEvaluator(),
new MyDataManager(),
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.registerEndpointGenerator(new HelloWorld());
/// Not registering legacy method.
// 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!