Skip to main content
Home  ›  Docs › Feature

WebAPI - Automatic WebServices for your Apps

Warning ⚠️: New Docs Available

These are old docs and we haven't found the time to completely move them. You will find comprehensive new docs on docs.2sxc.org.

Introduced in Version 06.05

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

  1. Very basic example: App, Demo
  2. Simple Feedback-Form example with a separate edit/manage view: App, Demo
  3. 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

  1. The convention is NameController.cs and the class should have the same name.
  2. 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

  • throw(new Exception…);

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?

  1. 2sxc(...) requests a 2sxc controller for the module within the brackets. 
  2. webApi.get(...) executes an HTTP-GET command against a web service
  3. the parameter "Categories/All" says to call the Categories Controller (in the file CategoriesController.cs) and the method "All"

Further supported verbs are:

  1. webApi.get(...)
  2. webApi.post(...)
  3. 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: 
    • $2sxcmoduleId ).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:
    • $2sxcmoduleId).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!