We have a project where UI code will be developed by the same team but in a different language (Python/Django) from the services layer (REST/Java). The code for each layer exits in different code repositories and which can follow different release cycles. I'm trying to come up with a process that will prevent/reduce breaking changes in the services layer from the perspective of the UI layer.

I've thought to write integration tests at the UI layer level that we'll run whenever we build the UI or the services layer (we're using Jenkins as our CI tool to build the code which is in two Git repos) and if there are failures then something in the services layer broke and the commit is not accepted.

Would it also be a good idea (is it a best practice?) to have the developer of the services layer create and maintain a client library for the REST service that exists in the UI layer that they will update whenever there is a breaking change in their Service API? Conceivably, we would then have the advantage of a statically-typed API that the UI code builds against. If the client library API changes, then the UI code won't compile (so we'll know sooner that there was a breaking change). I'd also still run the integration tests upon building the UI or services layer to further validate that the integration between UI and the service(s) still works.

  • 6
    Is it not being communicated to you when an API change is made? In these cases it's often best to version the API so your UI always has a working version. Then "upgrade" to the last API version as soon as possible. – Matt S Aug 6 '12 at 14:27
  • @MattS: I agree with you. But with or without communication: doing an upgrade to a changed API is much easier when the compiler tells you exactly all places you have to change in your code. Though the OP still misses to tell us how his Python code will provide a statically-typed API. – Doc Brown Nov 5 '12 at 17:18

In general, for methods of the API that are going away, pick a convention and 'deprecate' them, especially as soon as a full, replacement API is available and tested. Leave the old API in place (essentially), but tag the method signature metadata or insert a logging event so usage can be clearly identified.

Logging within the service API is one thing, but alerting consuming clients is another. For REST, I dont think there is a solid, standard practice. FourSquare API clients can discover deprecated methods even if the called method is successful (HTTP 200 code, however errorType will be set to 'deprecated'). Possibly a reasonable strategy for providing consuming clients with the opportunity for knowledge of a deprecated method within the API without causing breakeage.


Within your API guidance, suggest a date or build release number where the deprecated API will be removed completely. As you flesh our your strategy for deprecation, you will want to alert consumers of the API on what the proposed strategy is (how can they discover deprecated methods, how to transition to the replacement API, and when deprecated API will no longer be available if purged during an API cleanup), and solicit feedback from them to ensure the process is benificial to everyone.

| improve this answer | |

Versioning your API is another possibility. When a new version is deployed, leave the old version active as well and allow negotiation via the request. If you maintain the most recent 2 or 3 versions, then the UI code can upgrade at it's own pace.

| improve this answer | |

There are at least three questions at once, let's do them one-by-one

  • "is it a good idea to have a client library for the REST service?"

Most probably yes, as long as you don't want arbitrary REST calls directly scattered through all your UI code.

  • "is it a good idea to let the developer of the services layer create and maintain the lib?"

That depends on the persons in your team. The maintainer of the API should know both, the things available in the services layer as well as the requirements of the UI layer. So it may be either a person from the services layer or one from the UI layer, or (depending on the size and other tasks) a person independently from both teams.

  • [will we get an advantage from the fact that] "if the client library API changes, then the UI code won't compile"

Didn't you say the UI will be written in Python? That's not a statically-typed language, so I would not expect an immediate build break from an API change. I assume I got you wrong at this point and you have a statically typed API here - then you may get some advantages here as long as the build does not break when just adding some new features (like new optional parameters) to the API. Otherwise you will produce a lot of unneccessary overhead to your team.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.