标签: api-versioning

我一直在阅读有关ReST API的版本控制策略,而且它们似乎没有解决您如何管理底层代码库的问题.

比方说,我们正在做了一堆破更改API的-例如,改变我们的客户资源,使其返回单独forename和surname领域,而不是一个单一的name领域.(对于此示例,我将使用URL版本控制解决方案,因为它很容易理解所涉及的概念,但问题同样适用于内容协商或自定义HTTP标头)

我们现在有一个端点http://api.mycompany.com/v1/customers/{id},另一个不兼容的端点在http://api.mycompany.com/v2/customers/{id}.我们仍在发布v1 API的错误修正和安全更新,但新功能开发现在都专注于v2.我们如何编写,测试和部署对API服务器的更改？我可以看到至少两个解决方案:

• 为v1代码库使用源代码控制分支/标记.v1和v2是独立开发和部署的,必要时使用版本控制合并将相同的错误修复应用于两个版本 - 类似于在开发主要新版本的同时管理本机应用程序的代码库,同时仍然支持以前的版本.

• 使代码库本身了解API版本,因此您最终会得到一个包含v1客户表示和v2客户表示的单一代码库.将版本控制视为解决方案体系结构的一部分而不是部署问题 - 可能使用命名空间和路由的某种组合来确保请求由正确的版本处理.

分支模型的明显优势在于删除旧的API版本是微不足道的 - 只是停止部署适当的分支/标记 - 但如果您运行多个版本,最终可能会遇到一个非常复杂的分支结构和部署管道."统一代码库"模型避免了这个问题,但是(我认为？)会使得在不再需要时从代码库中删除已弃用的资源和端点变得更加困难.我知道这可能是主观的,因为不太可能有一个简单的正确答案,但我很想知道在多个版本中维护复杂API的组织如何解决这个问题.

我有一个基本的WebApi实现设置与默认值控制器.

在阅读关于RESTful WebApi Versioning的博客后,我决定将该软件包集成到一个新的WebApi项目中.

我已经添加了NuGet包Microsoft.AspNet.WebApi.Versioning来协助我的API版本控制.以下是我所遵循的包配置说明的URL:

https://github.com/Microsoft/aspnet-api-versioning/wiki/Configuring-Your-Application

我的价值观控制器非常简单.我已经将装饰添加到了我的Get方法中.这是代码:

[Authorize]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/values")]
public class ValuesController : ApiController
{
    // GET api/values
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
public string Get(int id)
{
    return "value";
}

// POST api/values
public void Post([FromBody]string value)
{
}

// PUT api/values/5
public void Put(int id, [FromBody]string value)
{
}

// DELETE api/values/5
public void Delete(int id)
{
}
}

不幸的是,只要我将以下代码行添加到控制器中,整个过程就会爆炸:

[Route("api/v{version:apiVersion}/values")]

这是一个正在返回的错误消息:

The inline constraint resolver of type …

我试图在REST API上启用版本控制,其中版本在标题中指定为"api-version":2.

根据这个教程,我只需要创建

VersionConstraint : IHttpRouteConstraint

和

VersionedRoute: RouteFactoryAttribute

用法是将[VersionedRoute("api/controllerName", 2)]属性应用于控制器,这是为特定版本设计的(例如,在这种情况下为版本2).

这一切都很好,但不幸的是,它全部在MVC5中,而我正在使用MVC6.因此,RouteFactoryAttribute并IHttpRouteConstraint不能正常工作.

我设法找到IRouteConstraint替换IHttpRouteConstraint(希望它可以工作),但我找不到替代品RouteFactoryAttribute.

如果有人可以使用MVC 6提供这样的示例,或者至少提到正确的类(理想情况下使用命名空间),我需要继承吗？

我在asp.net core(web api)中的路由有一些问题.

我有这个控制器(简化):

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[Controller]")]
public class DocumentController : Controller
{

[HttpGet("{guid}", Name = "GetDocument")]
public IActionResult GetByGuid(string guid)
{
    var doc = DocumentDataProvider.Find(guid);
    if (doc == null)
        return NotFound();

    return new ObjectResult(doc) {StatusCode = 200};
}


[HttpPost]
public IActionResult Create([FromBody] Document doc)
{
    //... Creating Doc

    //Does not work   
    //var val = CreatedAtRoute("GetDocument", new {guid = doc.Guid.ToString("N")}, document);
    //or this: CreatedAtRoute("GetDocument", new { controller = "Document", guid = doc.Guid.ToString("N")}, document);

    var val = CreatedAtRoute("GetDocument", new { version = …

我打算用Laravel框架创建一个API.并有可能成为API的多个版本,如果我继续发展它,如:v1,v2,v3,等等.

而不是只有一个Laravel框架副本,并通过为每个版本创建不同的目录对其中的API进行版本控制,我正在考虑为每个版本的API创建一个完全独立的Laravel框架副本.

例如,假设这是API的URL:website.com/api我正在考虑创建一个v1在该api目录中调用的目录,并在其中放入一个完整的Laravel副本.后来当我需要创建一个新版本的API时,我将创建另一个名为v2旁边的新目录,v1并在其中放入一个新的完整且独立的Laravel副本,依此类推.

这样,当我想访问API的版本1时,我将访问此URL:website.com/api/v1当我想访问版本2时,我将访问website.com/api/v2.

我的问题:这是个坏主意吗？这种方法的缺点是什么？

编辑:

为什么我会想到这种方法？

因为我想到了以下几点:

• 如果有一天我想要使用除Laravel之外的PHP框架创建新版本的API,该怎么办？
• 如果有一天我想用PHP以外的编程语言创建新版本的API会怎样？
• 如果有一天我想要升级到更新版本的Laravel并且该版本对最初创建API的版本进行了重大更改,该怎么办？

我正在开发一个需要对 FastAPI 端点进行版本控制的项目。我们希望通过 HTTP 接受标头对端点进行版本控制，例如：

headers={'Accept': 'application/json;version=1.0.1'}, 
headers={'Accept': 'application/json;version=1.0.2'}

像这样设置 api 版本似乎不起作用：

headers={'Accept': 'application/json;version=1.0.1'}, 
headers={'Accept': 'application/json;version=1.0.2'}

有谁知道我还需要做什么？

我正在试图弄清楚我对API项目架构的选择.

我想使用JAX-RS 1.0版创建一个API.此API从更大,更旧,更复杂的应用程序中使用远程EJB(EJB 3.0).我正在使用Java 6.

到目前为止,我可以做到这一点并且有效.但我对解决方案不满意.看我的包裹配置.我的问题在代码后面描述:

/api/
    /com.organization.api.v1.rs -> Rest Services with the JAX-RS annotations
    /com.organization.api.v1.services -> Service classes used by Rest Services. Basically, they only have the logic to transform the DTOs objects from Remote EJBs in JSON. This is separated by API version, because the JSON can be different in each version.
    /com.organization.api.v1.vo -> View Objects returned by the Rest Services. They will be transformed in JSON using Gson.
    /com.organization.api.services -> Service classes used by versioned Services. 
        Here …

当我这样做时use Foo:ver<1.0>;，将加载模块的1.0版本Foo。但是，当我这样做时会发生什么use Foo;呢？

我的解决方案中有以下控制器设置：

[Route("api/v{VersionId}/[controller]")]
[ApiController]
[Produces("application/json")]
[Consumes("application/json")]
public class MyBaseController : ControllerBase
{
}

[ApiVersion("1.0")]
[ApiVersion("1.1")]
public class AuthenticationController : MyBaseController
{
    private readonly ILoginService _loginService;

    public AuthenticationController(ILoginService loginService)
    {
        _loginService = loginService;
    }

    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status403Forbidden)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    [ProducesResponseType(StatusCodes.Status500InternalServerError)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [HttpPost("login")]
    public ActionResult<v1.JwtTokenResponse> Login([FromBody] v1.LoginRequest loginRequest)
    {
        var loginResult = _loginService.Login(loginRequest.Email, loginRequest.Password);
        if (loginResult.StatusCode != HttpStatusCode.OK)
        {
            return StatusCode((int)loginResult.StatusCode);
        }

        var tokenResponse = new v1.JwtTokenResponse() { Token = loginResult.Token };

        return Ok(tokenResponse);
    }
}  

在我的 API 的两个版本之间，此方法没有任何变化，因此从逻辑上讲，我想在我的文档中显示新版本仍然支持该方法。假设我们有第二个客户控制器，它的逻辑发生了一些变化，因此这就是我们拥有新版本 1.1 的原因，因为语义版本控制指示已添加新内容，但以向后兼容的方式添加。

运行这段代码时，自然一切都会构建得很好。代码是有效的，.net core 允许这种实现，但是，当涉及到 swagger …

约束引用异常

您好，我正在使用带有版本控制的 .Net 6 Web API，我的版本控制在 Swagger 中工作得很好，但是当我从 MVC Framework (.NET 6) 引用我的 API 时，我收到一个异常：

InvalidOperationException：约束引用“apiVersion”无法解析为类型。使用“Microsoft.AspNetCore.Routing.RouteOptions.ConstraintMap”注册约束类型。

    public static IServiceCollection AddApiVersioningConfig(this IServiceCollection services)
    {
        services.AddApiVersioning(cfg =>
        {
            cfg.DefaultApiVersion = new ApiVersion(1, 0);
            cfg.AssumeDefaultVersionWhenUnspecified = true;             // In case if the user doesn't specify the version, so we assume to use the default one (v1)
            cfg.ReportApiVersions = true;                               // This will mention which API the user is currently using (Header).
           

            // 1-  api/v1/clients/ => In order to read the segment that contains …