wildcard-api

<img src="https://github.com/reframejs/wildcard-api/raw/master/docs/images/logo-with-text.svg?sanitize=true" height=96 alt="Wildcard API"/>

• What is Wildcard
• Wildcard compared to REST, GraphQL, and other RPCs
• Usage

• More Resources

What is Wildcard

// The user is not logged-in.
// We abort.
// (This is basically how you define permissions with Wildcard
// which we will talk more about later.)
return;

"INSERT INTO todos VALUES (:text, :authorId);",
{text, authorId: user.id}

<sup>Open a ticket or chat with us if you have questions, feature requests, or if you just want to talk to us.
We enjoy talking with our users.


⇧ TOP ⇧</sup>

Getting Started

1. Add Wildcard to your Node.js server.

With Express:
~~~js
// Node.js server

const express = require('express');
const {getApiResponse} = require('wildcard-api'); // npm install wildcard-api

const app = express();

// Parse the HTTP request body
app.use(express.json());

app.all('/wildcard/*' , async (req, res) => {
  // `getApiResponse` requires the HTTP request `url`, `method`, and `body`.
  const requestProps = {
    url: req.url,
    method: req.method,
    body: req.body,
  };

  // The `requestProps` object is available in your endpoint functions as `this`.
  // For example, you can add `req.headers` to `requestProps` to be
  // able to access it in your endpoint functions as `this.headers`.
  requestProps.headers = req.headers;

  const responseProps = await getApiResponse(requestProps);
  res.status(responseProps.statusCode);
  res.type(responseProps.contentType);
  res.send(responseProps.body);
});
~~~

<details>
<summary>
With Hapi
</summary>

~~~js
// Node.js server

const Hapi = require('hapi');
const {getApiResponse} = require('wildcard-api'); // npm install wildcard-api

const server = Hapi.Server();

server.route({
  method: '*',
  path: '/wildcard/{param*}',
  handler: async (request, h) => {
    // `getApiResponse` requires the HTTP request `url`, `method`, and `body`.
    const requestProps = {
      url: request.url,
      method: request.method,
      body: request.payload,
    };

    // The `requestProps` object is available in your endpoint functions as `this`.
    // For example, you can add `request.headers` to `requestProps` to be
    // able to access it in your endpoint functions as `this.headers`.
    requestProps.headers = request.headers;

    const responseProps = await getApiResponse(requestProps);
    const response = h.response(responseProps.body);
    response.code(responseProps.statusCode);
    response.type(responseProps.contentType);
    return response;
  }
});
~~~
</details>

<details>
<summary>
With Koa
</summary>

~~~js
// Node.js server

const Koa = require('koa');
const Router = require('koa-router');
const bodyParser = require('koa-bodyparser');
const {getApiResponse} = require('wildcard-api'); // npm install wildcard-api

const app = new Koa();

// Parse the HTTP request body
app.use(bodyParser());

const router = new Router();

router.all('/wildcard/*', async ctx => {
  // `getApiResponse` requires the HTTP request `url`, `method`, and `body`.
  const requestProps = {
    url: ctx.url,
    method: ctx.method,
    body: ctx.request.body,
  };

  // The `requestProps` object is available in your endpoint functions as `this`.
  // For example, you can add `ctx.request.headers` to `requestProps` to be
  // able to access it in your endpoint functions as `this.headers`.
  requestProps.headers = ctx.request.headers;

  const responseProps = await getApiResponse(requestProps);
  ctx.status = responseProps.statusCode;
  ctx.body = responseProps.body;
  ctx.type = responseProps.contentType;
});

app.use(router.routes());
~~~
</details>

<details>
<summary>
With other server frameworks
</summary>

Wildcard can be used with any server framework.
All you have to do is to reply all HTTP requests made to `/wildcard/*`
with `getApiResponse`:
~~~js
// Node.js server

// This is generic pseudo code for how to integrate Wildcard with any server framework.

const {getApiResponse} = require('wildcard-api'); // npm install wildcard-api

const {addRoute, HttpResponse} = require('your-favorite-server-framework');

// Add a new route `/wildcard/*` to your server
addRoute(
  '/wildcard/*',
  async ({req}) => {
    // We assume that your server framework provides an object holding
    // information about the request. We denote this object `req`.

    // `getApiResponse` requires the HTTP request `url`, `method`, and `body`.
    const requestProps = {
      url: req.url, // The HTTP request url (or pathname)
      method: req.method, // The HTTP request method (`GET`, `POST`, etc.)
      body: req.body, // The HTTP request body
    };

    // The `requestProps` object is available in your endpoint functions as `this`.
    // For example, you can add `req.headers` to `requestProps` to be
    // able to access it in your endpoint functions as `this.headers`.
    requestProps.headers = req.headers;

    // We get the HTTP response body, HTTP status code, and the body's content type.
    const responseProps = await getApiResponse(requestProps);
    const {body, statusCode, contentType} = responseProps;

    // We assume that server framework provides a way to create an HTTP response
    // upon `body`, `statusCode`, and `contentType`.
    const response = new HttpResponse({body, statusCode, contentType});
    return response;
  }
);
~~~
</details>

1. Define an endpoint function

in Node.js:

~~~js
// Node.js server

const {endpoints} = require('wildcard-api');

endpoints.myFirstEndpoint = async function () {
  // The `this` object is the `requestProps` object we passed to `getApiResponse`. Because
  // the headers are set on `requestProps.headers`, we can access them over `this.headers`.
  // You can then, for example, use the headers for authentication.
  console.log('The HTTP request headers:', this.headers);

  return {msg: 'hello from my first Wildcard endpoint';
};
~~~

1. You can now "call" your enpdoint function from you frontend:

~~~js
// Browser

import {endpoints} from 'wildcard-api/client'; // npm install wildcard-api

(async () => {
  const {msg} = await endpoints.myFirstEndpoint();
  console.log(msg);
})();
~~~

<sup>Open a ticket or chat with us if you have questions, feature requests, or if you just want to talk to us.
We enjoy talking with our users.


⇧ TOP ⇧</sup>

Authentication

url: req.url,
method: req.method,
body: req.body,
// We pass the `headers` object
headers: req.headers,

<sup>Open a ticket or chat with us if you have questions, feature requests, or if you just want to talk to us.
We enjoy talking with our users.


⇧ TOP ⇧</sup>

Permissions

// The user is not logged-in.
// We abort.
return;

// `todoId` didn't match any todo.
// We abort.
return;

// The user is not the author of the to-do item.
// We abort.
return;

<sup>Open a ticket or chat with us if you have questions, feature requests, or if you just want to talk to us.
We enjoy talking with our users.


⇧ TOP ⇧</sup>

Error Handling

validatePhoneNumber(phoneNumber);

err = err_

return {validationError: {phoneNumber: "Please enter a valid phone number."}};

throw new Error("Password is too weak.");

return {validationError: "Password is too weak."};

data = await endpoints.getData();

err = err_;

// Your endpoint function throwed an uncaught error: there is a bug in your server code.
alert(
  'Something went wrong on our side. We have been notified and we are working on a fix.' +
  'Sorry... Please try again later.'
);

// The browser couldn't connect to the server.
// The user is offline or your server is down.
alert("We couldn't perform your request. Please try again.");

return {success: false};

return {success: true, data};

<sup>Open a ticket or chat with us if you have questions, feature requests, or if you just want to talk to us.
We enjoy talking with our users.


⇧ TOP ⇧</sup>

SSR

<sup>Open a ticket or chat with us if you have questions, feature requests, or if you just want to talk to us.
We enjoy talking with our users.


⇧ TOP ⇧</sup>

Options

:informationsource: If you need an option that Wildcard is missing, then open a new GitHub issue. We usually implement new options within 1-2 days.

• serverUrl
• argumentsAlwaysInHttpBody

serverUrl

argumentsAlwaysInHttpBody

<br/>
How to use Wildcard with SSR and Authentication.

<br/>
Explains how Wildcard works.

<br/>
High level discussion about Wildcard, RPC APIs, GraphQL, and REST.

<br/>
An example of a to-do list app implemented with Wildcard.

<br/>
Goes into depth of whether you should implement a generic API (REST/GraphQL),
or a custom API (Wildcard),
or both.
In general, the rule of thumb for deciding which one to use is simple:
if third parties need to access your data,
then implement a generic API,
otherwise implement a custom API.
But in certain cases it's not that easy and this document goes into more depth.

<sup>Open a ticket or chat with us if you have questions, feature requests, or if you just want to talk to us.
We enjoy talking with our users.


⇧ TOP ⇧</sup>