3.0: Creating Endpoints

Creating individual endpoints is not very complicated. If you have used Thomas's RestApi module before, the fundamental concepts will look very similar to you. All your routes are defined under /site/api/Routes.php. This folder will be created while you install the module (in case it's not, you can find the example content in the modules folder of this module under apiTemplate).

To add new routes, just add items to the array in the following format:

// [httpMethod, endpoint, HandlerClass::class, methodInHandlerClass, ["options" => "are optional"],

// A GET-request to /api/test/ returns the output of Example::test():
['GET', 'test', Example::class, 'test']

// A POST-request to /api/test2/ returns the output of Example::test2()
['POST', 'test2', Example::class, 'postTest']

// This setting allows OPTION-requests to /api/test/:
['OPTIONS', 'test', ['GET', 'POST']],

Instead of my Example-class, you can call any other class as well. You only need to consider that the called function has to be static.

If you don't like that your Routes.php is located under /site/api/Router.php, you can change that in the module's settings to a custom path if you want to.

You can also create groups, which makes it a bit easier to create multiple sub-routes for the same endpoint (for example it is a good idea to version your API):

[
  'v1' => [
    ['GET', 'posts', Posts::class, 'getAllPosts'],
  ],
  'v2' => [
    ['GET', 'posts', NewPostsClass::class, 'getAllPosts'],
  ]
]

This is going to create the following endpoints for your API:

/v1/posts
/v2/posts

AppApi brings a handy overview page on which you can see all the api-endpoints that are registered in your api. Go to "Setup"->"AppApi"->"See Endpoints" to see the full list. You can even generate an OpenAPI json there, which can be imported in api-tools like Postman or Insomnia.

Multiple levels for routes are possible, too. The following example can be very handy for a classic CRUD-endpoint:

[
  'v1' => [
        'order' => [
				    ['OPTIONS', '', ['GET']],
            ['POST', '', Orders::class, 'getAllOrders'],
            
            ['OPTIONS', 'new', ['POST']],            
            ['POST', 'new', Orders::class, 'createOrder'],

            ['OPTIONS', '{id:\d+}', ['GET']],
            ['GET', '{id:\d+}', Orders::class, 'getOrderById']
            
            ['OPTIONS', '{id:\d+}', ['POST']],
            ['POST', '{id:\d+}', Orders::class, 'editOrder']
            
            ['OPTIONS', '{id:\d+}', ['DELETE']],
            ['DELETE', '{id:\d+}', Orders::class, 'deleteOrder']
        ],
    ]
]

This will create the following endpoints:

/v1/order/      // get all orders
/v1/order/new   // create a new order
/v1/order/{id}  // get, edit or delete a specific order

An optional fourth parameter can be set to add some automatic checks to a route:

Parameter	Type	Example	Description
auth	boolean	true	When true, authentication is required. Throws exception if not logged in.
roles	array	['admin', 'editor']	If set, one of the roles in the array is required to use the route.
application	int	42	If set, the route is only allowed if the requesting apikey belongs to the application with this id.
applications	array	[3, 5, 42]	Only the application-ids in the array are allowed to use the route
handle_authentication	boolean	false	If set to false, all authentication-checks (apikey, tokens, ...) are disabled.

You are free to combine the parameters in an array:

['POST', 'test2', Example::class, 'postTest', [
  'auth' => true,										// Only a logged-in user can access the route
  'roles' => ['admin', 'editor'],		// Only admins and editors can access
  'applications' => [3, 5, 42]			// Only the applications with id 3, 5 or 42 can access
]]

And then, there is an optional 5th index in the definition-array, that can contain data for the documentation of the endpoint. Look at chapter 3.4: Add-Documentation to lear more about that.

---

➡️ Continue with 3.1: Output Formatting
⬅️ Back to 2.4: Double JWT