Is it good practice to consume both the REST and SOAP API for a particular service?

Question

I am in the planning phase of a project that will use a 3rd party service that supports both REST and SOAP. The SOAP API is more mature and thus supports more operations.

I'd love to depend only on the REST API, but specific use cases have forced the use of the SOAP API. So really there are two options:

1. Depend ONLY on the SOAP API to do my business logic
2. Depend on the REST API AND fall back to the SOAP API when necessary

Some opinions on both would be great. And if it is a good idea to consume both in a single application, what are some common best practices and pitfalls?

Answer 1

Just because an API is written using SOAP doesn't necessarily mean it can't follow REST principles. So this is rather hard to answer without knowing the specific details of the API.

If the REST principles are adhered in the design of the SOAP API, then switching content types should be fairly trivial.

The most important principles here to adhere is the stateless principle. If the API is stateless, then the semantic of each request does not depend on the state of the connection, you would be able to switch between different content types safely.

There are other principles that would make it easier to combine the SOAP and REST API, such as if the SOAP and REST API identified resources in a uniform format, i.e. Uniform Interface principle. These are surmountable if not followed, but makes switching types significantly easier and less fiddly.

Answer 2

Will you ever have direct interaction between data obtained through the REST API and SOAP API? If so you'll be required to create "translation" code for them to be interoperable which might be hard or expensive to do.

If they never interact directly I'd say to use the REST one when you can and fallback otherwise.

Be aware that you'll have to be ready to upgrade when newer capabilities come to the REST API.

Answer 3

Look at the likely future roadmap for the APIs (what the vendor's realistically likely to do, not just what they say they have planned). If the SOAP API will be maintained on at least an equal footing with the REST API, using just the SOAP API is a viable option long-term. If however the SOAP API is likely to hit end-of-life and not be maintained, with the REST API being brought up to match and then all new features being only in the REST API, the recommended course would be to use the REST API where possible and treat the SOAP API as a fallback. In the latter case also plan on migrating any usage of the SOAP API over to the REST API at some point to guard against being caught unawares by removal of the SOAP API by the vendor.