This blog is part of a series, checkout other entries!
- FlexDeploy Loves Oracle API Platform: Series Overview
- FlexDeploy Loves Oracle API Platform: Provisioning the Gateways
- FlexDeploy Loves Oracle API Platform: Managing APIs
- FlexDeploy Loves Oracle API Platform: Automating Gateway Downtimes
Oracle API Platform provides a centralized location to develop and manage your APIs. Once development is complete the APIs are deployed throughout your environments, known as Gateways in Oracle API Platform. This is all accomplished through a single UI within API Platform. Because of this you may be asking “Why use FlexDeploy or any DevOps tool for that matter?”. As it turns out there are still a few shortcomings in API Platform where FlexDeploy can fill in the gaps.
- Rolling back API changes
- Deploying consistent versioned APIs to the Gateways
- Managing back end integrations along with the API
Among the above reasons the chief concern is deploying consistent versioned APIs. Currently there is no way to deploy an API iteration, other than the current iteration, to a Gateway via the UI. As a result all kinds of headaches can arise particularly if two changes are being worked simultaneously. Lets take a look at how we can tackle some of these concerns in FlexDeploy.
What’s in our toolbox?
Before we get into the approach for managing the APIs, lets take a look at the operations we have available so we can come up with a good solution. The 5.1 release of FlexDeploy provides extremely robust plugin operations for Oracle API Platform.
- ExportAPI will export a json file from the API Platform server. Additionally we have the option to export a specific API iteration.
- Returns an output for the exported API iteration.
- ImportAPI will only import the API json file into the API Platform server. Also includes options to skip the import if no changes are detected and to apply grants.
- Returns outputs for the API iteration and API id.
- DeployAPI as the name suggests..deploys the API to a Logical Gateway. We have several options here to set statuses, states, and descriptions upon deployment. Deploying a specific API iteration is also possible.
Now that we have a firm grasp of what we have available its time to decide on an approach that works for us. Here are some options.
Option 1 – Deploying the API json
Option 1 is what I will call the traditional FlexDeploy approach. The build workflow exports the API from the API Platform server and saves it to the Artifact Repository.
Subsequently the deploy workflow imports the API and then deploys the API to the Gateway.
The largest benefit of this approach is also perhaps the biggest drawback. The import step prior to deployment ensures that your API will be persisted through any accidental deletions or environment migrations. On the flip side this also means any changes made since the build took place will be lost. Lucky for us, option 2 will address this.
Option 2 – Deploying the API iteration
Option 2 is the preferred approach in my opinion. It is similar to Option 1 but it removes the import step and relies solely on the API iteration. Because of this we are able to keep any changes made to the API on API Platform that are not part of the build. The build workflow is the same as before with the notable exception that we are saving our API Iteration in the Artifact Repository.
As mentioned, notice the absence of the import step in our deploy workflow. Instead, we read the API iteration into a variable and use that for the deployAPI step.
Option 3 – Creating APIs from source control
The last option I want to show is quite a bit different from the previous two, particularly during build. In the first two options we are relying on APIs that already exist in API Platform. However, for this last option, we are going to build directly from a source control system instead. This is the most controversial option so far so lets look at the pros and cons.
Audit record of API changes
Manage the API source code alongside the back end
Continuous Integration supported with source control
Easy to copy/paste APIs
Initial setup can be daunting
Requires knowledge of the API json structure
Impacted by Oracle’s changes to json schema
I’m not going to show the build workflow for this option as it largely depends on the source control system of your choosing and has no API Platform specifics. I’m also not going to show the deploy as its actually the same as Option 1! That’ right. Option 1 and 3 are identical with the exception of the build workflow.
Which option is right for you?
That depends. In most cases I would argue Option 2 is the way to go as it allows preservation of the current API source on API Platform. However, Option 3 really shines when you have a large implementation with a lot of APIs that happen to be pretty similar. You could even go so far as to have a ‘template’ API utilizing FlexDeploy properties that is reused across the board. Happy coding!