API

This module allows you to create application endpoints that can be used to interact with the application from the outside, such as other applications and more.

Security Warning

When creating custom API endpoints, always protect them with proper authentication middleware. See the Security Best Practices guide to learn how to secure your endpoints with moduleKey validation.

API ModuleRead more on the Crowdin Developer Portal.

Sample

JavaScript

index.js

import crowdinModule from '@crowdin/app-project-module';

const app = crowdinModule.express();

const configuration = {
  baseUrl: 'https://123.ngrok.io',
  clientId: 'clientId',
  clientSecret: 'clientSecret',
  name: 'Sample App',
  identifier: 'sample-app',
  description: 'Sample App description',
  dbFolder: import.meta.dirname,
  imagePath: import.meta.dirname + '/logo.png',
  api: {
    default: true,
    docFile: import.meta.filename,
    endpoints: [
      {
        key: 'generate-report',
        name: 'Generate report',
        description: 'Get your report',
        url: '/report',
        method: 'GET'
      }
    ]
  }
};

const crowdinApp = crowdinModule.addCrowdinEndpoints(app, configuration);

/**
 * @openapi
 * /report:
 *   get:
 *     tags:
 *       - 'Report'
 *     summary: 'Test'
 *     operationId: test.report
 *     parameters:
 *       -
 *         name: userId
 *         in: query
 *         required: true
 *         schema:
 *           type: integer
 *           example: 102
 *     responses:
 *       200:
 *         content:
 *          application/json:
 *            schema:
 *              properties:
 *                data:
 *                  type: object
 *                  properties:
 *                    reportUrl:
 *                      type: string
 *                      example: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
 */
app.get('/report', async (req, res) => {
  try {
    // Always specify moduleKey to restrict access to authorized modules only
    const { client, context, subscriptionInfo } = await crowdinApp.establishCrowdinConnection({
      authRequest: req,
      moduleKey: ['my-api-module'] // Only allow access from specified modules
    });
    // check subscribe
    // get crowdin data
    // endpoint logic
    res.status(200).send({ reportUrl: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf' });
  } catch (e) {
    return res.status(403).send({ error: 'Access denied' });
  }
});

app.listen(3000, () =>  console.log('Crowdin app started'));

TypeScript

index.ts

import crowdinModule from '@crowdin/app-project-module';
import type { ClientConfig, CrowdinClientRequest } from '@crowdin/app-project-module';
import { RequestMethods } from '@crowdin/app-project-module/modules/api';

const app = crowdinModule.express();

const configuration: ClientConfig = {
  baseUrl: 'https://123.ngrok.io',
  clientId: 'clientId',
  clientSecret: 'clientSecret',
  name: 'Sample App',
  identifier: 'sample-app',
  description: 'Sample App description',
  dbFolder: import.meta.dirname,
  imagePath: import.meta.dirname + '/logo.png',
  api: {
    default: true,
    docFile: import.meta.filename,
    endpoints: [
      {
        key: 'generate-report',
        name: 'Generate report',
        description: 'Get your report',
        url: '/report',
        method: RequestMethods.GET
      }
    ]
  }
};

const crowdinApp = crowdinModule.addCrowdinEndpoints(app, configuration);

/**
 * @openapi
 * /report:
 *   get:
 *     tags:
 *       - 'Report'
 *     summary: 'Test'
 *     operationId: test.report
 *     parameters:
 *       -
 *         name: userId
 *         in: query
 *         required: true
 *         schema:
 *           type: integer
 *           example: 102
 *     responses:
 *       200:
 *         content:
 *          application/json:
 *            schema:
 *              properties:
 *                data:
 *                  type: object
 *                  properties:
 *                    reportUrl:
 *                      type: string
 *                      example: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
 */
app.get('/report', async (req, res) => {
  try {
    // Always specify moduleKey to restrict access to authorized modules only
    const { client, context } = await crowdinApp.establishCrowdinConnection({
      authRequest: req as CrowdinClientRequest,
      moduleKey: ['my-api-module'] // Only allow access from specified modules
    });
    // check subscribe
    // get crowdin data
    // endpoint logic
    res.status(200).send({ reportUrl: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf' });
  } catch (e) {
    return res.status(403).send({ error: 'Access denied' });
  }
});

app.listen(3000, () =>  console.log('Crowdin app started'));

In this example, we create a new endpoint /report that returns a link to a report. The endpoint is protected by the Crowdin authentication mechanism. It’s described in the OpenAPI format, which allows you to generate documentation for your API.

Security Note: The moduleKey parameter ensures that only the specified modules can access this endpoint. Without it, any user with a valid JWT token from any module in your app could potentially call this endpoint. For more details, see the Security Best Practices guide.

Configuration

Parameter	Description	Default value
default	Enable default endpoints for other modules	true
docFile	Path to the jsdoc file	import.meta.filename
endpoints	List of custom endpoints	-

The endpoints parameter is an array of objects with the following properties:

{
  name: string;
  url: string;
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  description?: string;
}

Default Endpoints for Project Integration

The Project Integration module automatically includes the API module with the default: true parameter. This means the default endpoints are enabled without additional configuration:

Endpoint	Method	Description
/crowdin-files	GET	Get a list of synced files
/file-progress	GET	Get file translation progress
/integration-files	GET	Get integration data
/crowdin-update	POST	Update crowdin data
/integration-update	POST	Update integration data
/all-jobs	GET	Get all jobs
/job-info	GET	Get job info
/jobs	GET	Get job info (deprecated)
/jobs	DELETE	Cancel job
/settings/schema	GET	Get settings schema with field types and options
/settings	GET	Get application settings
/settings	POST	Update application settings
/sync-settings	GET	Get auto-sync files list
/sync-settings	POST	Update auto-sync files configuration
/login-fields	GET	Get integration login form fields *
/login	POST	Integration login *

^* The /login-fields and /login endpoints are only available when the Project Integration module is configured with a loginForm.