2sxc 6.5 provides a simple way to include your own WebAPI controllers. Following Convention-over-Configuration, your controllers are available automatically if they are placed in the right folder and inherit the correct interface - so it's super simple to use.
Quick-Learning
The fastest way to learn this is to install these apps in the catalog and look at the code
- Very basic example: App, Demo
- Simple Feedback-Form example with a separate edit/manage view: App, Demo
- Advanced AngularJS + WebApi example: App, Demo
Creating your WebAPI Controller
Where to put the API-Controllers
Place these in your Apps API folder, so if your App had a folder
/Portals/0/2sxc/MyGallery/
Then your API folder would be
/Portals/0/2sxc/MyGallery/api/
Note that "api" and "API" will work.
Name of the API Controller File, Class and Inheritance
- The convention is NameController.cs and the class should have the same name.
- You should inherit from the class: ToSic.Sxc.WebApi.SxcWebApiController
Example of such an API controller
The easiest way to discover the WebAPI is to download/install the demo App we provided.
Understanding the Internals of the WebAPI Controller
How does controller get wired/the route get registered?
Basically there is a root-route which is registered for all 2sxc-app APIs. This is usually:
- /DesktopModules/2sxc/API/App/{app-name}/{controller}/{action}
- /DesktopModules/2sxc/API/App/auto-detect-app/{controller}/{action}
The 2sxc Route-Resolver will use standard procedures to then find the …/api/{controller}Controller.cs and this will automatically be used. The command will also be mapped to that. More advanced routes cannot be mapped and are never necessary.
Returning Values
This is simply done by returning the value from the method, like
return true;
Returning Errors
This is just like any C#, just throw an error. So you can let an internal error just bubble through
- DataController.Create("badContentTypeName", new Dictionary<string, object>); // will throw an error
Or you can explicitly throw an error like
Returning Entities
This is very simple, just look at the demo-apps. We're basically returning dynamic, anonymous typed objects.
Using the WebAPI / Calling it from JavaScript
Basically you must create a simple JSON-Request from your script. But for security reasons, the request must contain anti-forgery tokens, moduleIds and more. To make this easier, the best way to do it is to let the $2sxc JavaScript controller create the main request for you, like this:
- $2sxc(622).webApi.get('Categories/All')
What does this do?
- 2sxc(...) requests a 2sxc controller for the module within the brackets.
- webApi.get(...) executes an HTTP-GET command against a web service
- the parameter "Categories/All" says to call the Categories Controller (in the file CategoriesController.cs) and the method "All"
Further supported verbs are:
- webApi.get(...)
- webApi.post(...)
- webApi.delete(...)
Additional parameters work as follows:
- If you have one additional parameter (number or text) it will be treated as the ID-parameter. So
- $2sxc( moduleId ).webApi.get('Categories/Details', catId)
- ...will end up calling the .../Categories/Details?id=...
- If you need multiple parameters in the url (like ?id=27&newName=GreatNewName ) then add it as a object { id: 27, newName: "GreatNewName} like this:
- $2sxc( moduleId ).webApi.get('Categories/Rename', { id: $scope.SelectedCategory.Id, name: $scope.EditCategory.Title })
- if you also need post variables (for sending many values), use the third parameter, like:
- $2sxc( moduleId).webApi.post('Categories/Update', id, { Title: $scope.EditCategory.Title, Description: $scope.EditCategory.Description })
You can find many samples demonstrating this in the WebApi demo-apps.
So: Try out the demo-app to discover everything :)...
...and have fun!