Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Support for Custom Response Header #895

Discussion options

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?

You must be logged in to vote

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 in...

Replies: 3 comments 13 replies

Comment options

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.

You must be logged in to vote
1 reply
Comment options

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

Answer selected by commonsensesoftware
Comment options

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
	}
}
You must be logged in to vote
2 replies
Comment options

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

Comment options

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

Comment options

You must be logged in to vote
10 replies
Comment options

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;
 });
Comment options

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

Comment options

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;
})
Comment options

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"));
Comment options

That works. Thank you! No further questions!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

AltStyle によって変換されたページ (->オリジナル) /