Sitefinity Web API

Hi guys, 

We are working on the implementation of new Rest Services in Sitefinity. With this functionality we are aiming to replace the existing backend services, expose Sitefinity data via modern intuitive rest endpoints and make possible and easier the integration with external platforms(link) and services.

We’ve chosen to use OData + WebApi as a framework,  because of the tight integration between those two. OData exposes an out of the box protocol and infrastructure that we can leverage to more easily develop this feature and is used among major companies and products which will allow Sitefinity to integrate with those easily.

Configuration for the services:

Here is the structure of the configuration (images attached):

Profile

A profile will group a set of types that will be exposed through the service. The profile will also contain a base url for all of the exposed types. Each profile will relate to a separate Route and will contain different metadata depending on the types specified in the configuration. A profiles can have as many types as needed  depending on the data to be exposed. Each profile will have to be explicitly entered and enabled in the configuration.

Type

Each profile consists of types. You will be able to register persistent types that you want to be exposed to the outside world. The type has several important configurations available:

• The UrlKey by which to expose the type. For example if the profile has the URL “api/odata”, and you register the news with a UrlKey “news”, the all of the news items will be available at “api/odata/news”;
• Each type can have methods exposed to it. These methods will be used to have more semantic urls. For example if you have the URL query /api/odata/news?$filter = startswith(Title, ‘News’)&$expand=’Tags’&$select=Title&$orderby=DateCreated, this can simple be mapped to the method /api/odata/news/filterednews

Properties

Each type will expose three types of properties – Persistent, Navigational, Calculated. For each property you will be able to choose a user-friendly alias that suits your needs. For example if the property name “Content” does not mean anything, you can change that to be served as “Description”.

Basic

These represent the properties that  are stored in the database and can be modified. Furthermore these properties can be configured to enable Sorting, Filtering. This is handy in case you do not to filter by a property that has no index on it.

Navigational

These represent the associations for the specified type. For example you can have a registered type BlogPost and you will be able to expose the property “Parent” which will map to the parent Blog item and will be able to be served using the OData query operator “$expand”. Navigational properties will be supported for standard Content relations like BlogPost-> Blog, for Taxonomies and for Related Data.

Calculated

These represent those properties that will be dynamic and not persistent in the database. For example if you would like to deliver the url of a related image, you can configure a Calculated property – “ImageUrl” that will hold the absolute URL of the related image.

CRUD

The CRUD operations will follow the OData protocol with some adjustments for sitefinity’s lifecycle.

Relations

As per the Odata protocol, there will be endpoints available for modifying the relations of a type(click). For example if you have the relation NewsItem -> Tags, you will be able to use these endpoints to add/remove tags from the NewsItem.

There are still many unknowns.

For example - What kind of security mechanism should we use - should we use the current one or switch to API Keys ?

We would be happy to know that you think of the proposed solution. Are there any specific requirements or requests, which you would like us to address?

We look forward to receiving your feedback!

Will you replace all existing services or will we now have a mix of wcf, service stack and now webapi?

Auth tokens and basic auth pls. Don't make it count towards user count or require logging out

@betty Oh this is another service, nothing is being replaced

 Also, yes api key please AND standard auth.  Will let me have users authenticate normally, while we can also sell\provide api keys for external users.

Hi,

I have previously expressed my dislike of OData already so there's probably little chance in trying to change your mind now that you have obviously decided to use it. Regardless, here's a link that expresses some of the concerns: stackoverflow.com/.../9579090

As betty mentioned in her comment, we'll now have three different API stacks on our hands with no clear indication as to a) when to use which and b) how long this latest incarnation of API will last until you decide to use yet another framework. I was very happy when Servicestack came onto the scene in the SF backend since I had been using it on a number of projects before and I enjoy using it for its architectural simplicity and general ease of use and now you seem to be abandoning it again for something else. How many more times will this be happening?

With all that said, I do have a few questions:

1. Will this API support custom types as well as the built-in types? All your samples show only built-in types and I hardly have a need to expose these but I need to expose the custom types we built with module builder nearly every time.

2. Will the API allow me to expose data that is set to be viewable by everyone and that is displayed on pages with anonymous access to everyone? This covers 80% of my use cases but it's impossible to achieve with the WCF API as it is locked down by default. If I need to expose publicly visible events, news, or custom types as JSON so I can consume them from some client-side JS widget I do *not* want to have to authenticate anywhere. This needs to just work, no API key, nothing. There is a reason these items' view permissions are set to "everyone" and the API needs to take this into account. Writing to the API is another story of course, but reading *must* consider the content item's permission settings.

3. I like the general idea of configuring access to types by using profiles. However, usually there will not be a single mapping for a single content type, i.e. if I need to expose a custom content type such as "Product" I usually need to have different configurations for different use cases. Example: Lists will display less properties than single item views and thus I would need to be able to create at least two different configurations for the "Product" type, one with the bare minimum of properties and one with a full features list of properties. In your screen shot, mappings seem to be keyed by the type name which would imply a single configuration for a type only.

4. How can I make sure the API only does what I want it to do? OData is a generic one-size-fits-all framework that allows all kinds of queries once you grok the syntax. In the spirit of "secure by default", however, I don't want to allow any more queries than the clients actually need. How will I be able to make sure this is the case and that I don't accidentally allow queries I don't need, especially ones that use navigation properties and could result in involuntary n+1 queries?

As far as auth is concerned: SF auth using the existing cookies that are already in the browser as well as API keys would be nice.

Thanks and kind regards,

Hardy

Hi all,

@betty The current services will continue to work, but will most likely be replaced with Odata in the future.

@Hardy There is no rule when to use each framework - it depends on which best suits your needs. We are aiming to make the new services with OData to be more flexibale, user-friendly, fast and easily pluggable. Our end goal is to make the data exposed with a minimal amount of effort. However you are free to develop with any of the existing frameworks.

 As to your questions:

1. Yes, you will have the ability to expose custom dynamic types. Furthermore we are considering to enable the exposing of custom (non-sitefinity) types, for which you would be able to register a custom data source provider from where to fetch the data (be it from Entity Framework, In memory, File System etc..)

2. Yes, you will be able to configure the authentication mechanism to allow anonymous or restricted access  to your data.

3. The mappings are configured for a type, but this type can be registered in multiple profiles. For example, you might register a profile named "Full data" with your type and expose the large portion of the properties. The root for the profile will be "api/full"  and the service for the type will be "api/full/news". Afterwords you would register another profile "Less data", listening at "api/less", with the same type, which would be available at  "api/less/news",  but with less properties.

4. For each property (be it a relation property pointing to another databse object or just a plain field), you will have the ability to disable it and this will not allow anyone to use it it any operations. Furthermore, we will have restrictions on properties to allow filtering and sorting on them, because the backing fields in the database for those properties might not have appropriate indexes. We want to make these services fast as well, so we will add extra attention to making them optimized against n+1 query problems.

Martin

@Martin

1) Will there be a self-documenting endpoint page that can be enabled\disabled?

2) Please leave us ServiceStack as an option for custom services...you can freely kill WCF when you re-do the backend UI, but don't tie power-users to OData.

Looks good. A few things I'm currently using a RESTful add-in someone put on github which isn't bad, but not as rich as it could be.  A few things I'd like to see in this:

* RESTful not just someone saying it's REST so resource based endpoints, media types, HTTP verbs, etc.

* Authentication schemes (including OAuth 2.0)

* API key support (with tracking of the use of the key)

* Hypermedia (resources that describe their own capabilities and interactions)

I know, a lot to ask, but far too many times API implementations are done that say they're RESTful but are really RPC oriented and just pretend to be.

Thanks