Implication of implementing Apigee's API design best practices could be a customization of the backend service

[pranavchaudhary]

Hi,

I've been reading Apigee learning material on API design and how to best use Apigee one book in particular - Web Design: The Missing Link talks about pragmatic REST, REST Model being resource driven, the data driven paradigm and it even gives advice on how to name paths. Generally, it drives home the point the best practice to design and call a REST API is to stick with verb+path concept where the path is a resource name eg:POST /dogs.

My question is ultimately Apigee is exposing an existing backend web service and not creating it's own API/ws so you might inherit a "function-oriented" API by doing a WSDL import and that is no fault of yours, it's just how the backend is designed. For example, Oracle has an OOTB SOAP WS to validate accounts and the way the current path is named /validateAndCreateAccounts doesn't conform to what the book and Apigee preach because use Nouns and not Verbs in paths.

Current State of Apigee URL: https://{host-name}/basepath/validateAndCreateAccounts

Current State of API call: POST /basepath/validateAndCreateAccounts

So, if my understanding is correct, in order to bring this up to the pragmatic REST standard we will have to do something in Apigee..we will have to make some "X" change to the state of the API at the point of importing a WSDL in order to bring it up to standard. For example, instead of triggering that URL the

new URL would be: https://{host-name}/basepath/{noun-equivalent}

new API call: POST /basepath/{noun-equivalent}

Now, my question: Is doing this customizing the backend service? More generally, is this what the book is asking us to do and is it safe and "correct" to do this when Apigee's role is to "expose" the service.

Not just this but the fact that I can take an existing SOAP webservice and expose it as a REST webservice does this implications of breaking changes with existing consumers of that backend..before Apigee came in play

[pranavchaudhary]

@Sai Saran Vaidyanathan

@Dino @Dino-at-Google

[pranavchaudhary]

@Dino @Dino-at-Google Can you please help me out here?

@Sai Saran Vaidyanathan @Anil Sagar @ Google

[ChrisHood]

Hi Pranav,

You have a lot of elements to your question, so let's walk through some of them step by step.

1. The great news around Apigee is that we have policies for things like SOAP to REST that allow you to expose your existing SOAP webservices in a restful way, and that ultimately make more sense to the developers who will be consuming those APIs.

2. At a high level, the key is to develop a consistent API Product Strategy that will help you to expose your backend services in an easier way, or a more understandable way. The overall product strategy for your APIs should consider naming conventions that keep everything organized and designed consistently.

3. Apigee as a gateway allows you to do some fun things, like add security, track your APIs with analytics, and generate more consumable data services. By placing the restful design in front of your backend, you won't have to change your apps that are using the APIs, and you can adjust your backend as needed.

4. There are a ton of philosophical thoughts around how to design APIs. One approach is to break your services down into buckets and combine them into functional features. In general, I believe you have the right concept for this in your question. For example, the Oracle validateAndCreateAccounts can be simplified like this:

	GET /v1/accounts/validate/{uid}
	POST /v1/accounts/create
	GET /v1/accounts/{uid}

This is simple to understand, and the complexity of the backend, Oracle, or SOAP responses are hidden from the developer.

If we continued with this approach, you could then begin to add on different backend services for accounts, or single sign on elements or any other account types, without changing the design structure that much.

	GET /v1/accounts/validate/{uid}/oracle
	GET /v1/accounts/validate/{uid}/internal
	POST /v1/accounts/create/oracle
	POST /v1/accounts/create/internal

5. Finally, Apigee establishes a facade in front of your complex backend systems. Depending on how you manage your APIs and how you manage your backend systems, and also how you manage your applications that use your APIs, is part of the management process. Using things like version numbers as I did above, help developers have a better understanding of what is used. If you change the backend or the APIs with new features that are not backwards compatible, then applications will need to update their code to support the new version of your APIs. But in general, with the RESTful facade in place, the apps won't need to be updated as often, and you can change backend functionality with new data as often as you'd like.

Hopefully this helps. If you have more questions, please let me know.

Chris

[pranavchaudhary]

@Chris Hood Appreciate your answer, patience and thoroughness, really do! Couple follow ups :-

1. I have 3 follow ups here.

• I'm not aware of any "policy" per se for REST-to-SOAP protocol transformation but I think what you're talking about is the radio button you can click on after doing a WSDL import. The other radio button right next to it is for a SOAP pass through proxy. Is that what you're talking about when you say "policy" ?
• Would you agree that simply clicking that radio button doesn't make it a REST API ? There are other constraints to satisfy for REST like statelessness, uniform interface constraint etc. that are not met by clicking this button and doing nothing more after that.
• "and that ultimately make more sense to the developers who will be consuming those APIs."
  • Are you saying REST APIs make more sense that SOAP APIs? Can you elaborate further and explain why?

3. "you won't have to change your apps that are using the APIs, and you can adjust your backend as needed."

Sorry, I'm not trying to be difficult here I think it's just that as a novice I tend to get very confused, very easily.

Q: My backend is a SaaS vendor...I can't change the backend code or whatever you're referring to when you use the word "adjust" I don't have access to the backend to adjust it.

I think what you mean is have seperate proxies, correct?

Allow me to restate my use case: Prior to Apigee coming in the tech landscape there were point to point integrations between clients and the provider of this SOAP web service. The client would need to conform precisely to Oracle's expected request payload format i.e. It has to be a XML SOAP message etc and you have to have the word "validateAndCreateAccounts" in your URL.

Now, if I expose this SOAP WS as a "REST" API on Apigee will that break the pipe?

I think what your saying is have 1 proxy be a SOAP pass through for those old clients and make the other one a REST-SOAP-REST proxy, correct?

legacy: /validateAndCreateAccounts

new: /accounts

Can you confirm the above calls make sense to you?

4. Thank you for that explanation and I know you're only using examples and concepts but I'm just hung up on on something you wrote. I need you to read this https://docs.oracle.com/en/cloud/saas/financials/19a/oeswf/account-combinations-for-validation-Accou... first. The operation "validateAndCreateAccounts" natively validates an account i.e. returns a valid/invalid status and CREATES the account on the server if it is valid.

• It is inherently a POST call in my opinion, do you agree?
• Do you agree that it is not possible to break up the call into validate and create separately the way you did? If not I will have to think again because I don't see how this would work...it's one target endpoint so if you do GET /v1/accounts/validate/{uid} that request is routed to /validateAndCreateAccounts and triggers that operation on the backed server ultimately. So, you would have retrieved the status and created a resource violating the Idempotent property of the HTTP GET method written in the HTTP specification.
• Lastly, how come you have the words "validate" and "create" in your URLs? The whole point of me wanting to encapsulate that was because the book says verbs don't belong in the URL and we should use nouns. So my plan was to convert POST /validateAndCreateAccounts to POST /accounts period. Does that make sense?

5. I need you to explain your last sentence a little more. "the apps won't need to be updated as often"....can you spell out for me in which cases would the apps now not need to be updated? Or generally how so? I don't get it.

[ChrisHood]

1. SOAP -> REST // REST -> SOAP

This article gives you most of the answers to what you are asking.
https://docs.apigee.com/api-platform/develop/exposing-soap-service-api-proxy

There are 2 features in Apigee that handle this; First by importing a WSDL, or the second by creating a pass-through proxy that uses Apigee's SOAP to REST policy. The link above explains both.

2. Changes to Backend Systems

If you are unable to modify the backend, or you won't need to change the backend, then you will have to focus on the proxy updates that you are using to integrate with that backend. And NO, you won't break anything, because the proxy as a facade simply points to the correct URL structure that you need (in your Oracle example.)

You are correct with this:

legacy: /validateAndCreateAccounts
new: /accounts

But what happens when you have /accounts being used in an application, and Oracle changes their service to something else like /validateCreateAct? In this scenario, things break, because /accounts is still pointing to /validateAndCreateAccounts. At that point you'll need to update, but again, this works because apigee is simply routing to where it needs to go.

3. Structure of your API Calls

Yes, I'm simply using examples, and I'm not familiar enough with the backend or how Oracle confirms, or processes /validateAndCreateAccounts. If the service does infact validates and then creates an account all at once, then you're suggestion of simply having /accounts would make sense. However, how would you structure this if you added other backend services that also needed to validate or create accounts? What if you had 3 different systems and Oracle was only one of those systems? How would you differentiate between creating an account on Oracle vs. creating an account on one of the other systems? In Apigee there are routing rules that can help you achieve this, but you also want to structure your calls so they fit with each scenario. In general though, in a one for one scenario that you are attempting to produce, you can definitely stick with POST /accounts which points to /validateAndCreateAccounts

4. Apps being updated

I covered this a little bit above. Here is a basic flow.

1. Application points /accounts in Apigee
2. /accounts points to /validateAndCreateAccounts in Oracle

For as long as the Oracle side doesn't change, then in theory, the proxy in Apigee also doesn't need to change. And also, in theory, the application itself doesn't need to change. No coding or new deployments are required.

But now let's say that Oracle makes a change, (again just an example), and that change is breaks the API. Let's say /validateAndCreateAccounts no longer works. Well in this scenario you go into Apigee and change the target to the new URL. The only coding that is done is inside of Apigee. The application itself doesn't have to be updated because it is still pointing to /accounts and as long as you've made the update in Apigee, no new release or deployment of the application needs to happen.

I believe that covers everything you were asking? Does it make sense?