This repository has been archived by the owner. It is now read-only.
DISCONTINUED - Umbraco REST services for content, media and members
Switch branches/tags
Nothing to show
Clone or download
Latest commit 8ad623d May 30, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
build bumps version Mar 12, 2018
src bumps version Mar 12, 2018
.gitignore BUmps version, fixes build AllowInsecureHttp by config fixes issuer c… Sep 29, 2017
LICENSE Initial commit Apr 13, 2015
README.md Update README.md May 30, 2018

README.md

This project has been discontinued in favor of Umbraco Headless

We're no longer making any updates to this project

You're welcome to clone the project and continue using and altering it but Umbraco HQ does no longer support it




Below is the archived readme and documentation




Umbraco REST API

The Umbraco REST API is for content, media, members & relations. It's Based on the HAL specification (GitHub link) and is using a wonderful WebApi implementation of HAL which can be found on GitHub: https://github.com/JakeGinnivan/WebApi.Hal

Installation

Umbraco REST API can be installed via Nuget:

Install-Package UmbracoCms.RestApi

This package will also install another add-on for Umbraco called Identity Extensions.

Once installed, a readme is displayed with a snippet of code to enable the REST API. This can be done using OWIN startup classes and because the IdentityExtensions package has been installed, a few classes have been added to your ~/App_Startup folder. The easiest way to enable the REST API is to copy the code snippet from the readme that is displayed:

app.ConfigureUmbracoRestApi(new UmbracoRestApiOptions()
	{
		//Modify the CorsPolicy as required
		CorsPolicy = new CorsPolicy()
            {
                AllowAnyHeader = true,
                AllowAnyMethod = true,
                AllowAnyOrigin = true
            }
	});

then open the file: ~/App_Startup/UmbracoStandardOwinStartup.cs

and paste this snippet just underneath this line of code: base.Configuration(app);

That's it, you've now enabled the REST API.

Discovery

A great way to browse Umbraco's REST service is to use the great html/javascript HAL Browser. The starting endpoints are:

  • /umbraco/rest/v1/content
  • /umbraco/rest/v1/media
  • /umbraco/rest/v1/members
  • /umbraco/rest/v1/relations

Rest API V2 startup

There will be a number of changes in the upcoming rest api project - the startup owin class has been streamlined - it could look like the sample below:

using Microsoft.Owin;
using Owin;
using TestSite.App_Startup;
using Umbraco.Web;
using Umbraco.RestApi;
using Umbraco.RestApi.Security;

[assembly: OwinStartup("UmbracoRestApiStartup", typeof(UmbracoRestApiStartup))]

namespace TestSite.App_Startup
{    
    public class UmbracoRestApiStartup : UmbracoDefaultOwinStartup
    {
        protected override void ConfigureMiddleware(IAppBuilder app)
        {
            app.UseUmbracoRestApi(ApplicationContext);
            var authServerOptions = new UmbracoAuthorizationServerProviderOptions
            {
                //needed when not running on SSL and testing
                AllowInsecureHttp = true                
            };
            app.UseUmbracoTokenAuthentication(authServerOptions);

            //If you wish to allow the REST API endpoints to be authenticated with a user's back office cookie, enable this
            // https://our.umbraco.org/Documentation/Implementation/Rest-Api/#security
            //app.UseUmbracoCookieAuthenticationForRestApi(ApplicationContext);

			base.ConfigureMiddleware(app);
        }
    }
}



Below is the documentation migrated from Our Umbraco




REST APIs in Umbraco

Information about REST APIs in Umbraco

Creating your own

It is entirely possible and quite easy to create your own REST APIs for Umbraco by utilizing ASP.Net's WebApi in conjunction with Umbraco's UmbracoApiController's.

Using an existing REST API platform

A free add-on for Umbraco 7.3+ has been built by the Umbraco HQ that gives you a nice REST API for working with content, media, members & relations. The source code for this project lives at GitHub: https://github.com/umbraco/UmbracoRestApi

It's Based on the HAL specification (GitHub link) and is using a wonderful WebApi implementation of HAL which can be found on GitHub: https://github.com/JakeGinnivan/WebApi.Hal.

Installation

Installation can be done via Nuget:

Install-Package UmbracoCms.RestApi

This package will also install another add-on for Umbraco called Identity Extensions.

Once installed, a readme is displayed with a snippet of code to enable the REST API. This can be done using OWIN startup classes and because the IdentityExtensions package has been installed, a few classes have been added to your ~/App_Startup folder. The easiest way to enable the REST API is to copy the code snippet from the readme that is displayed:

app.ConfigureUmbracoRestApi(new UmbracoRestApiOptions()
{
	//Modify the CorsPolicy as required
	CorsPolicy = new CorsPolicy()
        {
            AllowAnyHeader = true,
            AllowAnyMethod = true,
            AllowAnyOrigin = true
        }
});

then open the file: ~/App_Startup/UmbracoStandardOwinStartup.cs

and paste this snippet just underneath this line of code: base.Configuration(app);

If you would like to have the Umbraco back office cookie used to authenticate the REST API you can add this line of code too:

app.UseUmbracoCookieAuthenticationForRestApi(ApplicationContext.Current);

That's it, you've now enabled the REST API.

Discovery

A great way to browse Umbraco's REST service is to use the great html/javascript HAL Browser. The starting endpoints are:

/umbraco/rest/v1/content /umbraco/rest/v1/media /umbraco/rest/v1/members /umbraco/rest/v1/relations

We will be enabling a single root endpoint that list these HAL links in the very near future!

Security

Currently the REST API is secured based on back office user logins. In the future this will be enabled for front-end member logins and we'll allow for an easy approach for configuring the security during startup/configuration of the REST API.

In the meantime, there are a couple of options for securing the REST API. The first (as mentioned above), is to enable cookie authentication for the REST API. This is the same cookie authentication that is used to authenticate back office requests. So, if you are using the REST API endpoints from within your application, then you can enable this by adding this line of code to your OWIN startup:

app.UseUmbracoCookieAuthenticationForRestApi(ApplicationContext.Current);

The other approach is to authenticate the request using Bearer tokens. This is a requirement if you are consuming the REST API from outside of your domain.

IMPORTANT

Since the REST API is currently only secured against back office user logins it is important to understand that if you want to use the REST API for applications that exist outside of the web domain, that you do not hard code back office user login credentials. In the future when the security for the REST API can be more flexible it would be advised to authenticate your apps based on a member's credentials that your app users would need to enter.

To enable token based authentication, see the file that has been installed at ~/App_Startup/UmbracoAuthTokenServerExtensions.cs which contains a lot of detail about how to enable a token authentication server. In its simplest form, this can be enabled with the following startup code:

app.UseUmbracoBackOfficeTokenAuth();

There are plenty of options and extensibility points that can be set for the token auth server. The IdentityExtensions package installs these extension methods for you which are based on ASP.Net conventions. For more info about tokens, authentication and authorization visit ASP.Net's documentation.

Here's an example token request for the default endpoint that the above method creates:

POST /umbraco/oauth/token HTTP/1.1
Host: localhost
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=YOURUSERNAME&password=YOURPASSWORD

Of course you'll need to modify YOURUSERNAME and YOURPASSWORD with valid Umbraco user credentials.

The response will look something like:

{
  "access_token": "DUxMxH415liyvWcqtMQ9qMStu2rBGcWELRTlB1lUncAraw_xzyXUWmo2QNklI1YLlwQ_eliUV9x3t4MxJJ2lzraYlCGQIkKbzQ487G6vekbIPnaQ0mnEWwFBnSRK6bZa2CL_GdhTrlkMnrCDvhNjYh4U2lbvmAWuz8_23BIkH2K9G9JbVeTSnpk1o666fnITkbeLM602OSZqUT",
  "token_type": "bearer",
  "expires_in": 86399
}

You can then use the value from access_token in the requests to the REST API endpoints, for example:

GET /umbraco/rest/v1/content HTTP/1.1
Host: localhost
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer DUxMxH415liyvWcqtMQ9qMStu2rBGcWELRTlB1lUncAraw_xzyXUWmo2QNklI1YLlwQ_eliUV9x3t4MxJJ2lzraYlCGQIkKbzQ487G6vekbIPnaQ0mnEWwFBnSRK6bZa2CL_GdhTrlkMnrCDvhNjYh4U2lbvmAWuz8_23BIkH2K9G9JbVeTSnpk1o666fnITkbeLM602OSZqUT