View on GitHub

URSA

Ultimate ReSt Api

Home Documentation Roadmap Log
Download this project as a .zip file Download this project as a tar.gz file

URSA is designed to do as much as possible automatically. While there is always an option of explicitely defining the behaviour, in most of the cases you’d like to stick to the defaults.

Building API

Build an API is as easy as 01, 10, 11. Define a class implementing any of the interfaces listed below and this should make your class up and running:

Aim is to have as least of the interference in the ordinary code as possible, thus interfaces are used instead of a class.

The framework uses several naming conventions, thus you can have an influence on how the URLs and HTTP methods are assigned. In general, mapping of HTTP methods to class methods is as follows (method should start with any of these words - if followed by other, those words should be upper camel cased):

Additionally, methods containing HTTP method names (Get, Put, Post, Delete) are mapped to their HTTP equivalents.

As for URLs generated, these are the basic rules:

Optionally, it is possible to define URSA.Web.Mapping.RouteAttribute on an assembly level containing controllers to define an entry point for those controllers effectively adding an additional segment prior to controller/method path.

To visualize, below are few examples of how the methods are mapped to URLs:

With *[assembly: URSA.Web.Mapping.RouteAttribute(“api”)] these would become respectively:

Converters

URSA comes with several convertes transforming incomming parameters and request bodies into strongly typed values. These includes:

Practically, it would be possible i.e. to implement a converter accepting image/jpeg which would provide a strongly typed System.Graphics.Image instance out of it.

API Documentation

In order to obtain an automatically generated HYDRA documentation a proper request to controller’s base URL with HTTP OPTIONS and supported HTTP Accept header. It is also possible to manually invoke a specific RDF serialization by sending to controller’s base URL a HTTP GET request with ?format=[XML|RDF|JSONLD|Turtle]. Optionally, if the assembly has a defined URSA.Web.Mapping.RouteAttribute it is possible to obtain a documentation for whole entry point with same aproaches described about by calling that entry point path.

This is still experimental thus it might still not be fully compliant with HYDRA itself. There are also still few things HYDRA does not cover, thus some extensions have been introduced. Still it’s a powerfull description that allows to define operations, hypermedias and data types.

Initialization

In order to have everything setup, all you need to do is to add (assuming that you have URSA.Web referenced):

using URSA.Web;

public class Global : System.Web.HttpApplication
{
	protected void Application_Start(object sender, EventArgs e)
	{
		this.RegisterApis();
	}
}

or in whatever initialization code you have out there. This will discover all implementations of URSA.Web.IController type, register in the route tables, assign handlers, automatically generated HTTP OPTIONS handler, etc.

As for OWIN hosting environment, you can do the similar (assuming that you have URSA.Owin referenced):

using Owin;
using URSA.Web;

public class Startup
{
	public void Configuration(IAppBuilder appBuilder)
	{
		appBuilder.RegisterApis();
	}
}

Additional behaviour

There are few additional features that can be added to the initialization stage:

Example:

using Owin;
using URSA.Web;

public class Startup
{
	public void Configuration(IAppBuilder appBuilder)
	{
		appBuilder
			.WithCorsEnabled()
			.WithIdentityProvider<FakeIdentityProvider>()
			.WithBasicAuthentication()
			.RegisterApis();
	}
}