iOS消费API设计 [英] iOS consuming API design

问题描述

我将要为 Web 应用程序开发一个 iOS 应用程序.(网络应用使用代码点火器)

I am going to develop an iOS app for a web application. (The web app uses code igniter)

我将创建一个 iOS 应用将使用的 API 服务.

I am going to create an API Service that the iOS app will consume.

我正在考虑创建一个api版本，这样当web api发生变化时，iOS应用就会知道.

I am thinking of creating an api version, so when the web api changes, the iOS app will know.

关注点:

• 当 Web 应用程序 api 发生变化时，iOS 应用程序将需要更新(除非我保留旧版 api 可用.这是一个不错的选择)
• 如果在未更新 Web 应用程序 API 时更新了 iOS 应用程序，这也会导致问题

我的 iOS 应用是否应该指定它需要的 api 版本?

Should my iOS app specify the version of the api it requires?

• 如果 iOS 应用 api 小于 web api:显示消息:请更新 iOS 应用
• 如果 iOS 应用 api 大于 web api:显示消息:请更新 web 应用

这是最佳做法吗?

我是否应该为每个版本都创建一个 api 类并在它们更改时扩展以前的版本并覆盖方法?

Should I make an api class for every version and extend the previous version and override methods when they change?

示例

ApiV1 extends CI_Controller
{
   function list_customers(){//Code}
   function saveSale() {//Code}
}

ApiV2 extends ApiV1
{ 
   function saveSale()
   {
      //New way of saving sale
   }
}

如果我更改数据库结构，v1 api 将不再工作，会发生什么?(例如，更改了数据库表的名称?)

Also what happens if I make a change to the database structure where the v1 api will no longer work? (Example, changed the name of a database table?)

推荐答案

一般来说，您希望在您的服务 API 和您的客户端之间创建一个相当松散的耦合.通常，会有多个版本的客户端总是四处飘荡，您希望尽可能少地强制用户升级.

In general, you want to create a fairly loose coupling between your service API and your client. As a rule, there will be multiple versions of the client always floating around in the wild, and you want to force upgrades on users as rarely as possible.

API 版本的完整版本在 Web 服务中实际上很少见，通常只对应数据模型、安全模型等的重大更改.允许多个版本共存可能需要对服务进行一些额外的工作，但是让现有客户继续工作是值得的.

A full rev of an API version is actually somewhat rare in web services, and usually only corresponds to significant changes to the data model, security model, etc. Allowing multiple versions to coexist may require some extra work on the service, but can be worth it to allow existing clients to keep working.

为此，请在设计前仔细考虑您用作独立于当前客户端 UI 需求的抽象实体的模型".(如果您想对您的特定情况进行更具体的思考，您可能希望发布有关建模您的需求的单独问题.)但是不要太担心永远提前解决所有需求，因为需求将不可避免地发生变化.

To that end, think carefully in the design up front about the "model" you're using as an abstract entity independent of the current client UI needs. (If you want more specific thinking around your particular case, you may wish to post a separate question about modeling your needs.) But don't worry too much about solving all of the needs forever in advance, because requirements will inevitably change.

完成此操作后，请通过在服务 API 中构建一些版本控制概念来为未来做好准备.需要考虑的一些事项:

Once you've done this, do prepare for the future by building some notion of versioning into the service API. Some things to consider:

1. 作为 URL 方案一部分的显式版本或最初在例如身份验证握手.这是一种干净地命名客户端访问内容的方法.(前者会导致服务上的显式 URL 路由，后者在破解身份验证令牌后需要更多的体操来路由.)
2. 一个已知的错误响应，表示此 API 调用已过时"，较早的客户端可以识别出它来告诉用户他们的客户端需要更新

在服务上，您的设计可以像您注意到的一样明确，使用带有方法覆盖的控制器，但在更高的级别上:saveSale 方法不太可能在版本之间表现出很大差异.在 V1 中似乎更有可能有一个 saveSale 方法来做基线事情，然后可能例如在 V2 中保存了一些额外的数据.发生这种情况时，如果存在额外的数据位，代码可能只有条件分支.所有这些都是另一种说法，即服务 API 实际上不会经常发生不兼容的更改.list_customers 可以随着时间的推移返回更多信息.这并不一定意味着您的 API 需要新版本，或者旧客户端不应该只是忽略他们不需要的任何额外信息.

On the service, your design can be as explicit as you note, with a controller with method overrides, but at a little higher level: the saveSale method is somewhat unlikely to behave very differently between versions. It would seem more likely to have a saveSale method in V1 that does the baseline thing, and then maybe e.g. saves some extra bit of data in V2. When that happens, the code might just have conditional branching if that extra bit of data is present. All of this is another way of saying that a service API doesn't actually change incompatibly that often. list_customers could return more information over time. That doesn't necessarily mean that your API needs a new version or that old clients shouldn't just ignore any extra information they don't need.

回复:关于数据库表名的最后一个问题.这些可能会在内部发生变化，但您不需要将它们明确映射到客户端看到的内容.API 是一个稳定的接口，理想情况下应该隐藏不断发展的服务的实现细节.

Re: your final question about database table names. Those may change internally, but you aren't required to map those explicitly to what the client sees. An API is a stable interface that should ideally hide the implementation details of your ever-evolving service.

当您认为 API 需要做的事情的总体情况发生了显着变化，以至于无法和平地满足现有客户的需求时，您将选择修订 API.当您认为在服务上维护对某些客户端版本的支持比安装基础的价值更让您头疼时，您将选择弃用和淘汰某些客户端版本(一个非常特定于业务/案例的问题).

You'll choose to rev the API when, as a whole, you decide that the overall picture of what the API needs to do is significantly changed enough that it cannot peacefully serve the needs of existing clients. You'll choose to deprecate and obsolete certain client versions when you decide that maintaining support for them on the service is causing you more headache than the install base is worth (a very business/case specific issue).

祝你好运.

这篇关于iOS消费API设计的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！