API v2

Documentation for creating, understanding and maintaining API.

Defining an endpoint

All endpoints are defined in the folder routers. There exists a router for each module of the API, i.e a router for employee-related endpoints, another one for competence-endpoints and so on.

To define an endpoint, you either add to an already existing router, or you create a new router and make sure to import it in the routers/routers.ts file. This file bundles all the routers and passes it to the Express server.

router.get('/yourEndpoint', async (req, res, next) => {
  try {
    // Get data from Dataplattform using reports
    const data = await getReport<TypeOfYourDataFromReport>({
      accessToken: req.accessToken,
      reportName: 'yourReportName',
    })
    // Aggregation of data
    const aggregatedData = yourPotentialAggregationOfTheData(data)
    
    // Send response
    res.send(aggregatedData)
  } catch (error) {
    // Pass potential error to handler
    next(error)
  }
})

Endpoint with parameters (i.e 'email')

Certain endpoints require parameters, and they are passed and handled like this:

// The fourth argument here is passed to be able to type the req.query
router.get<unknown, unknown, unknown, { email?: string }>(
  '/yourEndpointWithEmailAsParameter',
  async (req, res, next) => {
    try {
      if (!req.query.email) {
        throw {
          status: 400,
          message: "Param 'email' is missing.",
        } as ParamError
      }

      const data = await getReport<TypeOfYourDataFromReport>({
        accessToken: req.accessToken,
        reportName: 'yourReportName',
        queryParams: {
          email: req.query.email,
        },
      })

      const aggregatedData = yourPotentialAggregationOfTheData(data)

      // Send response
      res.send(aggregatedData)
    } catch (error) {
      // Pass potential error to handler
      next(error)
    }
  }
)

Testing the endpoints

To test the endpoints, you will need to obtain your access token. Log into the Folk-app (locally) and grab it under your browsers localStorage.

Then make a GET-request to https://localhost:3000/api/v2/<module>/<endpoint>, with Postman, curl or something similar. Remember to use your access token for Bearer-token authentication.