Routing
An endpoint URL provides access to a resource or a relationship. Resource endpoints are divided into:
- Primary endpoints, for example: "/articles" and "/articles/1".
- Secondary endpoints, for example: "/articles/1/author" and "/articles/1/comments".
In the relationship endpoint "/articles/1/relationships/comments", "articles" is the left side of the relationship and "comments" the right side.
Namespacing and versioning of URLs
You can add a namespace to all URLs by specifying it at startup.
// Program.cs
builder.Services.AddJsonApi<AppDbContext>(options => options.Namespace = "api/shopping");
Which results in URLs like: https://yourdomain.com/api/shopping/articles
Default routing convention
The library will configure routes for all auto-generated and hand-written controllers in your project. By default, routes are camel-cased. This is based on the recommendations outlined in the JSON:API spec.
// Auto-generated
[Resource]
public class OrderSummary : Identifiable<int>
{
}
// Hand-written
public class OrderLineController : JsonApiController<OrderLine, int>
{
public OrderLineController(IJsonApiOptions options, IResourceGraph resourceGraph,
ILoggerFactory loggerFactory, IResourceService<OrderLine, int> resourceService)
: base(options, resourceGraph, loggerFactory, resourceService)
{
}
}
GET /orderSummaries HTTP/1.1
GET /orderLines HTTP/1.1
The exposed name of the resource (which can be customized) is used for the route, instead of the controller name.
Non-JSON:API controllers
If a controller does not inherit from JsonApiController<TResource, TId>
, the configured naming convention is applied to the name of the controller.
public class OrderLineController : ControllerBase
{
}
GET /orderLines HTTP/1.1
Customized routes
It is possible to override the default routing convention for an auto-generated or hand-written controller.
// Auto-generated
[DisableRoutingConvention]
[Route("custom/route/summaries-for-orders")]
partial class OrderSummariesController
{
}
// Hand-written
[DisableRoutingConvention]
[Route("custom/route/lines-in-order")]
public class OrderLineController : JsonApiController<OrderLine, int>
{
public OrderLineController(IJsonApiOptions options, IResourceGraph resourceGraph,
ILoggerFactory loggerFactory, IResourceService<OrderLine, int> resourceService)
: base(options, resourceGraph, loggerFactory, resourceService)
{
}
}
Advanced usage: custom routing convention
It is possible to replace the built-in routing convention with a custom routing convention by registering an implementation of IJsonApiRoutingConvention
.
// Program.cs
builder.Services.AddSingleton<IJsonApiRoutingConvention, CustomRoutingConvention>();