Support for Custom Response Header

[brandonsmith86]

Our organization has a requirement to include the planned retirement date for a deprecated version. This information would be included in the response header, much like the deprecated-versions and supported-versions headers are now. I was hoping to simply extend the existing functionality, but I am not seeing any documentation, or even examples, of how to do that.

Can anyone tell me if this is possible, or do I need to roll my own so to speak?

[commonsensesoftware]

Starting in 6.0 this is now possible. The feature Sunset Policies implements RFC 8594, which satisfies this requirement. RFC 8288 is also supported so that you can provide additional links to published policies. It's worth noting that an API doesn't have to be deprecated to advertise a sunset date. You might know ahead of time that a supported API will deprecate and then fully sunset well in advance (ex: a year from now).

I'm behind on updating the documentation to fully outline the feature, but there is an open issue tracking that. You can see an example of how to use it here or take a look at the tests.

There is also now a client library to complement HttpClient which can detect this information and log information and warnings when new versions become available, versions are deprecated, or versions are about to sunset.

Happy to answer any more questions about how the feature works. In general, you just configure it from the ApiVersioningOptions. The policy can target a specific API, version, or combination of both. You still have to enable ReportApiVersions to output this information. I thought about separating it out, but I can't imagine why you'd want sunset policies separate from supported and deprecated versions.

[brandonsmith86]

This is great info. I will dig in tomorrow and get back to you with any questions.

[brandonsmith86]

After switching to the new version (v6.1), I am getting a Swashbuckle error: Conflicting method/path combination "GET DownstreamPath/{node_id}" for actions - neo4j_api.Controllers.QueryController.DownstreamPath (neo4j-api), neo4j_api.Controllers.QueryController.NewDownstreamPath. Seems it can no longer differentiate between different versions of the same endpoint.

Here's what my controller code looks like. The new version basically does nothing. This is simply to test the versioning functionaity.

[ApiController]
[Route("/")]
[ApiVersion(ApiVersions.V1_0, Deprecated = ApiVersions.V1_0_Deprecated)]
[ApiVersion(ApiVersions.V1_1, Deprecated = ApiVersions.V1_1_Deprecated)]
public class QueryController : ControllerBase
{
	/// <summary>
	/// GET request that returns a path of nodes downstream starting from the node specified as a parameter
	/// </summary>
	/// <returns>
	/// A path type which is derived from a list of Nodes and Relationships
	/// </returns>
	/// <param name="node_id">Name of starting node</param>
	/// <param name="limit_hops">Max number of hops to traverse from <paramref name="node_id"/></param>
	/// <param name="limit_nodes">Max number of paths to traverse</param>
	[Route("/DownstreamPath/{node_id}")]
	[HttpGet]		
	[MapToApiVersion(ApiVersions.V1_0)]
	[EnableQuery(AllowedQueryOptions = AllowedQueryOptions.Filter | AllowedQueryOptions.Select | AllowedQueryOptions.Expand)]
	public async Task<Models.v1_0.ApiResponse<Edge>> DownstreamPath(string node_id, int limit_hops = 2, int limit_nodes = 100)
	{
		// v1.0 code here
	}

	/// <summary>
	/// Version 1.1 of GET request that returns a path of downstream nodes
	/// </summary>
	/// <returns>
	///		An error message saying this version hasn't yet been implemented
	/// </returns>
	[Route("/DownstreamPath/{node_id}")]
	[HttpGet]
	[MapToApiVersion(ApiVersions.V1_1)]
	[EnableQuery(AllowedQueryOptions = AllowedQueryOptions.Filter | AllowedQueryOptions.Select | AllowedQueryOptions.Expand)]
	public Task<Models.v1_1.ApiResponse<Edge>> NewDownstreamPath(string node_id, int limit_hops = 2, int limit_nodes = 100)
	{
		// v1.1 code here
	}
}

[brandonsmith86]

@commonsensesoftware Just tagging you to make sure you see this.

[brandonsmith86]

I also tried separating the versions out into separate controllers, but I am still getting the same error.

[xavierjohn]

Here is a working example of multiple versions on the same controller.
https://github.com/xavierjohn/ApiVersionSample/blob/main/OpenApiExample/src/V1/Controllers/OrdersController.cs

hosted here
https://openapiversionsample.azurewebsites.net

[commonsensesoftware]

Great! This looks like it is due to #891, which is a bug. I have the fix, but it isn't published yet. The following should work around the problem:

services.AddControllers()
        .AddOData(
            options =>
            {
                options.RouteOptions.EnableKeyInParenthesis = false;
                options.RouteOptions.EnableKeyAsSegment = true;
            });

[brandonsmith86]

This did not resolve the problem. Still getting the same error. I really appreciate you guys spending the time to help me with this!

[brandonsmith86]

It's working! I commented out the below line and Swagger started working again. I'm assuming there's something I'm missing from your OData example?

services.AddControllers().AddOData(options => {
  options.Select().Filter().Expand(); //.AddRouteComponents("odata", EdmModelBuilder.Build());
  options.RouteOptions.EnableKeyInParenthesis = false;
  options.RouteOptions.EnableKeyAsSegment = true;
})

[commonsensesoftware]

Nice!

This happens because the native .AddRouteComponents will not work with API Versioning. Despite previous discussions with the OData team, they elected not to make their design extensible. It expects one EDM per route. API Versioning, however, allows one EDM per API version per route. Nearly every major version change of OData has required some level of refactoring for API Versioning support. 8.0 was a completely rewrite, which is a big part of why it took so long to release.

The API Versioning setup for OData is intentionally very similar:

// standard OData setup
// the only things honored here are global settings (so you don't have to do it multiple times)
services.AddControllers().AddOData();

// versioned OData setup
// EDMs are constructed from IModelConfiguration instances resolved from DI or
// you can use ODataApiVersioningOptions.ModelBuilder
services.AddApiVersioning().AddOData(options => options.AddRouteComponents("odata"));

[brandonsmith86]

That works. Thank you! No further questions!