Access rights

EPiServer Documentation says that access rights are automatically added for Administrators group, but it is good to verify it. Also, you might need other roles to access Service API. It is better to add a separate role for each of you partners accessing Service API. So you can remove partner access by removing roles when not needed.

Using this script you can see which roles have access to the Service API:

select * from tblUserPermission where GroupName = 'EPiServerServiceApi'

And with this script you can give read/write access:

insert into tblUserPermission (Name, IsRole, Permission, GroupName)
values ('Administrators', 1, 'ReadAccess', 'EPiServerServiceApi')
     , ('Administrators', 1, 'WriteAccess', 'EPiServerServiceApi')

For other roles, just replace Administrators to other role name.

Multiple Owin Startup classes

Sometimes you already have Startup class or another library also has it's own Startup and you are using it. At first, it is not obvious why authentication doesn't work. Token route (/episerverapi/token) returns 404 code and it looks like some routing doesn't work. And that's true - Service API authentication has its own routing configured. This is not a Web API route, but route added to Owin in Service API Startup class. It confused me at the beginning - I tried to find an issue with Web API configuration.

The solution is simple and documented - create another Startup class in your code and configure it as a default Startup class.

namespace Web
{
  public class Startup
  {
     public void Configuration(IAppBuilder app)
     {
         new EPiServer.ServiceApi.Startup().Configuration(app);
         new SomeLibrary.Startup().Configuration(app);
     }
  }
}

And configure it as default in Web.config:

<add key="owin:AppStartup" value="Web.Startup, Web" />
<add key="owin:AutomaticAppStartup" value="true" />

Web API attribute routing

I mentioned previously that authentication routes are managed by Owin, but Service API functional routes use Web API - when you get 404 for some functional route (for example, /episerverapi/commerce/entries/{startPage}/{pageSize}), then Web API routing is not configured properly. As described in the documentation, if you have your own Web API routing configured, disable Service API attribute routing configuration in Web.config.

<add key="episerver:serviceapi:maphttpattributeroutes" value="false" />

Testing Service API

It is highly recommended to create integration tests before starting Service API configuration. It will allow to verifying that your service API works step by step.

I have created sample test class as a gist - EPiServer Service API smoke tests. It is a XUnit test class. The test class verifies that authentication works and basic CRUD operations can be done.

Summary

While EPiServer Service API documentation covers most of the needed configuration, it is quite easy to miss something.