Headless CMS

Definitions & benefits

Tools & Concepts

Open source

Features

Authentication

Custom plugins & Marketplace

Webhooks

Multilingual CMS

APIs

Dynamic Zones

User roles & permissions

Content Modeling

Security & Privacy

Use Cases

Ecommerce

Blog

Forum

About Strapi

Life at Strapi

Releases & Roadmap

Events

Community

News

The Tutorials section covers an introduction to Strapi, some advanced technical content, product updates and releases. From basic workaround to in-depth development guides. 

Tutorials

How tos

Get all the latest updates, news and events.

Subscribe to the newsletter 📣

Strapi provides a set of powerful APIs to let the developers create custom API end-points. In this article, we will be creating a custom API endpoint from scratch.

## Prerequisites

Before you can jump into this content, you need to have the following:

1. Basic knowledge of JavaScript
2. Basic understanding of Strapi - [get started here](https://strapi.io/documentation/developer-docs/latest/getting-started/introduction.html).

## Installing Strapi

The following command will install a new Strapi instance with some ready-made configurations and data.

```bash
    npx create-strapi-app plugins-v4-1 --template corporate
```

Please, [check out the create-strapi-app node package page for learning about the different ways to install Strapi.](https://www.npmjs.com/package/create-strapi-app)


Once the installation is complete, the browser automatically opens a new tab. If not, navigate to `http://localhost:1337/admin/`.

If port is already used by an another process, please check the alternate port mentioned mentioned in the CLI output. Most of the time, it would be `8000` , `8080` or `1337`.

Complete the form to create the first administrator user of this Strapi application.


![form to create the first strapi admin user](https://paper-attachments.dropbox.com/s_27799A4C5AE5EB6BE5512B43881D4F101A6ECBA3EFB7A80F19E9F08911D732AE_1645339274420_image.png)

The `blog` template generates components, collection types, and a single type out of the box.

![MWRhRKIT.png](/uploads/MW_Rh_RKIT_5e25568ffc.png)



In this example, we show you how to create a custom API Endpoint GET /api/posts-report` which will provide a simplified report of collection type article.

```js

[
  {
    "id": 1,
    "title": "The internet's Own boy",
    "category": "story",
    "publishedDate": "Fri May 20 2022",
    "authorName": "David Doe",
    "authorEmail": "daviddoe@strapi.io"
  },
  {
    "id": 2,
    "title": "This shrimp is awesome",
    "category": "nature",
    "publishedDate": "Fri May 20 2022",
    "authorName": "David Doe",
    "authorEmail": "daviddoe@strapi.io"
  },
  {
    "id": 3,
    "title": "A bug is becoming a meme on the internet",
    "category": "tech",
    "publishedDate": "Fri May 20 2022",
    "authorName": "Sarah Baker",
    "authorEmail": "sarahbaker@strapi.io"
  },
  {
    "id": 4,
    "title": "Beautiful picture",
    "category": "nature",
    "publishedDate": "Fri May 20 2022",
    "authorName": "Sarah Baker",
    "authorEmail": "sarahbaker@strapi.io"
  },
  {
    "id": 5,
    "title": "What's inside a Black Hole",
    "category": "news",
    "publishedDate": "Fri May 20 2022",
    "authorName": "Sarah Baker",
    "authorEmail": "sarahbaker@strapi.io"
  }
]
```

## Generating a Basic API


The `npx strapi generate` command starts an interactive CLI session. In case you have `yarn` and `strapi` installed globally in your system, feel free to replace the `npx` command with `yarn`.

The following options may be selected. Please, notice that we have named our API `posts-report`.

Navigate to your `demoapp` folder and run `npx strapi generate` to create a custom API endpoint.

```js

    ? Strapi Generators (Use arrow keys)
    ❯ api - Generate a basic API
      controller - Generate a controller for an API
      content-type - Generate a content type for an API
      plugin - Generate a basic plugin
      policy - Generate a policy for an API
      middleware - Generate a middleware for an API
      service - Generate a service for an API
```

Make sure the api option is selected and click enter.


```js
    ? Strapi Generators api - Generate a basic API 
    ? API name // name your api
```

I am going to call my posts-report and select N for "Is this API for a plugin?”

```js
    ? Strapi Generators api - Generate a basic API 
    ? API name posts-report 
    ? Is this API for a plugin? (Y/n)
```

This will generate these files below

```js
    ? Strapi Generators api - Generate a basic API
    ? API name posts-report
    ? Is this API for a plugin? No
    
    ✔  ++ /api/posts-report/routes/posts-report.js
    ✔  ++ /api/posts-report/controllers/posts-report.js
    ✔  ++ /api/posts-report/services/posts-report.js
```

We can find these in the `/src/api/posts-report` folder.
This command creates a directory called `posts-report` within `src/api` directory. The `posts-report` contains three directories called `controllers`, `routes`, and `services`.



## Routes

Requests sent to Strapi on any URL are handled by routes. By default, Strapi generates routes for all the content-types (see [REST API documentation](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/rest-api.html)). [Routes can be added](https://docs.strapi.io/developer-docs/latest/development/backend-customization/routes.html#implementation) and configured. Once a route exists, reaching it executes some code handled by a controller.

Replace the code in `/src/api/posts-report/routes/posts-report.js` with the following lines of code.

```js
    module.exports = {
      routes: [
        {
          method: "GET",
          path: "/posts-report",
          handler: "posts-report.postsReport",
          config: {
            policies: [],
            middlewares: [],
          },
        },
      ],
    };
```

## Controllers vs Services

Controllers are JavaScript files that contain a set of methods called actions, reached by the client according to the requested [route](https://docs.strapi.io/developer-docs/latest/development/backend-customization/routes.html). Whenever a client requests the route, the action performs the business logic code and sends back the [response](https://docs.strapi.io/developer-docs/latest/development/backend-customization/requests-responses.html#responses). Controllers represent the C in the model-view-controller (MVC) pattern. In most cases, the controllers will contain the bulk of a project's business logic. But as a controller's logic becomes more and more complicated, it's a good practice to use [services](https://docs.strapi.io/developer-docs/latest/development/backend-customization/services.html) to organise the code into re-usable parts.

Services are a set of reusable functions. They are particularly useful to respect the DRY (don’t repeat yourself) programming concept and to simplify [controllers](https://strapi.gitee.io/documentation/v3.x/concepts/controllers.html) logic.


## Creating a Service

Services are basically not aware of the Koa’s `ctx` object(request and the response). It is supposed to be a flexible and reusable function. 

Replace the contents of `/src/api/posts-report/services/posts-report.js` with the following lines of code that use Strapi’s Entity Service API to fetch all pages:

```js


module.exports = {
  postsReport: async () => {
    try {
      // fetching data
      const entries = await strapi.entityService.findMany(
        "api::article.article",
        {
          fields: ["id", "title", "slug", "createdAt"],
          populate: {
            author: {
              fields: ["name", "email"],
            },
            category: {
              fields: ["name"],
            },
          },
        }
      );

      // reduce the data to the format we want to return
      let entriesReduced;
      if (entries && Array.isArray(entries)) {
        entriesReduced = entries.reduce((acc, item) => {
          acc = acc || [];
          acc.push({
            id: item.id,
            title: item.title || "",
            category: item.category.name || "",
            publishedDate: new Date(item.createdAt).toDateString() || "",
            authorName: item.author?.name || "",
            authorEmail: item.author?.email || "",
          });
          return acc;
        }, []);
      }

      // return the reduced data
      return entriesReduced;
    } catch (err) {
      return err;
    }
  },
};

```

In this code we are using Strapi’s [Entity Service API](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.html) to fetch all pages. To learn more about the flexible ways of populating the response, read the [Populating the Entity Service API](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/entity-service/populate.html#advanced-populating) documentation.

Once a service is created, it's accessible from [controllers](https://docs.strapi.io/developer-docs/latest/development/backend-customization/controllers.html) or from other services:

```js
    // access an API service
    strapi.service('api::apiName.serviceName');
    // access a plugin service
    strapi.service('plugin::pluginName.serviceName');
```

The list of services available can be logged from controllers and services:

```js
    console.log('strapi.services ', strapi.services);
    console.log('pages-report', strapi.service('api::pages-report.pages-report'));
```



## Creating a Controller

Controllers are functions that have direct access to the Koa’s `ctx`, hence a controller function is responsible for invoking our service on `request` and returning the results to the `response`.

Replace the code in `/src/api/posts-report/controllers/posts-report.js` with the following lines of code:

```js
    module.exports = {
      async postsReport(ctx, next) {
        try {
          const data = await strapi
            .service("api::posts-report.posts-report")
            .postsReport();
          console.log(data, "data");
    
          ctx.body = data;
        } catch (err) {
          ctx.badRequest("Post report controller error", { moreDetails: err });
        }
      },
    };
```

You may need to stop and re-start the server. Stop the server using `ctrl + c` in the terminal. Start the server using `yarn develop`. Make sure that your current directory is `demoapp`

![oH53_7P1.png](/uploads/o_H53_7_P1_83922e0455.png)


## Setting Permissions for the API


That’s all the code required for the use case. Send a get request to `/api/posts-report`. You will most probably get a 403 error.

![YyPbdVhA.png](/uploads/Yy_Pbd_Vh_A_f4e1d3e073.png)


In order to make the end-point accessible only to the authenticated users, go to the Settings > Roles > Authenticated. To be able to publicly access the end-point, please go to the Setting > Roles > Public in the Strapi dashboard.


![VFHlRAuk.png](/uploads/VF_Hl_R_Auk_10a3293468.png)


Please, check the postsReport for the Posts-report route and hit the save button.

![xllfMLaq.png](/uploads/xllf_M_Laq_cb59e4b9da.png)

Now, the custom API is ready for the public:

You can either just go here directly in your browser `http://localhost:1337/api/posts-report` or make a GET request using a service like postman or insomnia.

You should now see your data coming from your custom controller.

![zDq8VdNO.png](/uploads/z_Dq8_Vd_NO_c4ed6603b8.png)

![HfsRWnT4.png](/uploads/Hfs_R_Wn_T4_c4d445230f.png)

## Conclusion

In this article, we used Strapi’s [Entity Service API](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.html) to fetch and filter the results. It’s not the only way to accomplish this task. In Strapi, the fetching and filtering of results can be done using [Rest API, Query Engine API](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.html), and [GraphQL API](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/graphql-api.html) as well.

The Entity Service is the layer that handles Strapi's complex data structures like [components](https://docs.strapi.io/developer-docs/latest/development/backend-customization/models.html#components) and [dynamic zones](https://docs.strapi.io/developer-docs/latest/development/backend-customization/models.html#dynamic-zones) and uses the Query Engine API under the hood to execute database queries. This makes it a reasonable choice for this use case. Our example can be made as flexible as we need using the [filtering](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/entity-service/filter.html#logical-operators) & [advanced](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/entity-service/populate.html#advanced-populating) population techniques of the Entity Service API. 


You can go to this [Git Repository](https://github.com/PaulBratslavsky/custom-strapi-controller-tutorial) and check the readme file for complete guide. Let me know if you have any suggestions and what you will be building with the knowledge.






medium_Image - Media Section - Strapi 1 Icon.jpg

small_Image - Media Section - Strapi 1 Icon.jpg

thumbnail_Image - Media Section - Strapi 1 Icon.jpg

Image - Media Section - Strapi 1 Icon.jpg

How to Create a Custom API Endpoint in Strapi?

When I’m not working, I love to write, learn something new & read non-fiction.
