Last updated
Was this helpful?
Last updated
Was this helpful?
In this article, you will learn how to create your own API in the Umbraco backoffice. This is a great way to extend the functionality of the Umbraco backoffice and create custom endpoints for your use.
The end result for this article is to create a custom API called "My item API" in the Management API found at /umbraco/swagger/
.
To create a custom API, you need to create a class that inherits from Umbraco.Cms.Web.BackOffice.Controllers.ManagementApiControllerBase
.
The ManagementApiControllerBase
serves as the foundation for your custom API class. It provides essential functionalities and utilities required for managing APIs within the Umbraco backoffice environment.
We also use the VersionedApiBackOfficeRoute
attribute to define the route for our API. This attribute takes a string parameter that defines the route for the API. This route will be appended to the base route for the backoffice API.
Now that we have our class set up, we can add an action to get all items. We will use the HttpGet
attribute to define the HTTP
method and route for the action.
The AllItems
field is an in-memory list of items to simulate the use of a repository. We use the skip
& take
parameters here, so users of this endpoint can implement paging. We also use the PagedViewModel
to return the given items (10 by default), and then the total number of items.
AllItems is a local list:
The model for MyItem
is a basic class with an Id
and a Value
property.
We can now create some logic to return a response based on the ID
. The route parameter {id:guid}
specifies that the id
parameter should be a GUID
. Here we're creating a local in-memory list of items and returning the item with the matching ID
.
To note here is the use of the OperationStatusResult
method. This method allows you to return a response with a status code and a body. This is useful for returning error responses with additional information.
The method also needs an enum
operationStatus, as it will be attached to the response. This is a basic example, however, this OperationStatus
would be returned from your service layer, based on the error in the service layer method.
We can now add an action to create a new item. We use the HttpPost
attribute to define the HTTP
method and route for the action. Here we can see some validation logic.
If the value does not start with "New", we return a BadRequest
response with an error message. This highlights why we use the OperationStatusResult
method. We can return a detailed response.
We also use CreatedAtId<MyItemApiController>
, a helper method to create a response with a 201 Created
status code and a Location
header.
Now we can add an action to update an item. We can use the HttpPut
attribute to define the HTTP
method and route for the action.
Finally, we can add an action to delete an item. We can use the HttpDelete
attribute to define the HTTP
method and route for the action.
Now we have created the custom API for our Umbraco project. Below you can see the full example of the implementation.