Those of you who work with APIs already know why they’re important. But the rest of you may be wondering: What are APIs, and how you can utilize them with Oracle Dyn’s data?
API stands for Application Programming Interface. APIs allow two software programs to communicate with each other. It allows a developer to write a program that requests service from an Operating System or other applications.
Let’s explore how it’s applied with Oracle Dyn’s application interface and data. Every time you want to access or manipulate a set of data from Dyn’s applications, you will have to make a call via API. To help visualize this concept, imagine an API as the middleman between a programmer and an application. This middleman accepts a request, and, if that request is allowed, returns the data. The middleman also informs programmers about everything they can request, exactly how to ask for it, and how to receive it. Below is a model of how they all interact.
SOAP vs REST
Oracle Dyn offers two different types of Web Services Architecture. These are SOAP (Simple Object Access Protocol) and REST (Representation State Transfer). Before you spend hours determining the choice between SOAP and REST, consider that some Web services support one, and some the other. Both SOAP and REST are popular with developers working on system integration-based projects.
SOAP is a common choice for object-oriented programming suites. Many languages such as Java or .NET have built-in SOAP capabilities and can quickly interface with Dyn’s applications. However, many developers have found SOAP difficult to utilize in web development environments. For example, working with SOAP can involve writing a ton of code to perform extremely simple tasks because you must create the required XML payloads and envelope before the requests can be sent along.
REST offers a better alternative for those who have a web development background and is well-known among public API practitioners. Also, because REST inherits operations from HTTP, it’s an ideal choice when making the decision on how to open a web API. It relies on a simple URL in many cases. The majority of Web services that utilize REST rely on acquiring the necessary data utilizing URL approach. REST is less complicated than SOAP. Using REST can be difficult sometimes in the beginning; however, it pays off over time with clients’ resilience to changes. More information on REST be found on our help guide page.
In this blog, we will focus more on how to utilize REST to gather and modify data from Oracle Dyn’s applications. Below, I have outlined a table displaying the differences between SOAP and REST.
Let us begin by discussing use of an API with Oracle Dyn’s applications. The API has four basic processes. These are Login, Make Changes/Updates/Gather Data, Publish the changes, and Log-out.
In order for users to write or gather data from their account via the API, a Log-in session must be established. Both SOAP and REST could establish your session and provide a Token.
To create a REST API session, we will need to create a POST request. For context, the most frequently used HTTP verbs or methods, as they are properly called, are POST, GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. Below is a table displaying recommended return values of the primary HTTP methods.
To login, point the POST request to base-URI/session. You can set the Content-Type to application/json or application/xml and several others. What I recommend is setting the Content-Type header to application/json. We then can populate the request body with a JSON object named session containing Customer-name, User-name, and password. These credentials are your API credentials that were given when your account was created originally. Keep in mind not to pass your DynID credentials, as these are used for web UI access only. Once successful, you will receive a “token” under the “data” element of the response.
I will be utilizing Curl for my examples to illustrate this process further. You can utilize any other programming languages such as Python, PHP, Java, .NET, etc.. Curl is a tool to transfer data from or to a server utilizing one of the supported protocols such as HTTP, HTTPS and much more. Below is a sample of my REST session.
For further reading, instructions on how to create a session can be found in this self-help guide.
After logging in, the next step in the process is to create new data, make changes or request the desired data. While you can use it to login, the POST function is mainly utilized to create new resources. Once the creation is successful, you should be seeing HTTP status 200. This will return a Location header with a link to the newly-created resource with the 200 HTTP status. 400 level code would be for bad requests or malformed URL.
The GET Function is for reading or retrieving data. A happy HTTP response code you will see is “200 OK”. If there is an error encounter, you will see a return 404 which means “Not Found” or 400 for “BAD REQUEST”. Let’s go through an example below.
Let’s say you’re looking to set your A records’ TTLs from 2 hours to 1 hour. The best approach to go about this is utilizing the GET and PUT (make changes and updates). Obviously, when making any changes, you first want to make sure you’re logged in and have your Session Token. Make sure you have that handy for any changes you make.
Once logged in, the next important information to get is your record ID for each record, in order to easily adjust the TTLs. You will need to use a GET command to retrieve the record ID, and this can be done with this guide for each record type.
An example would be such:
It’s worth noting that each API call you make will have a job ID. Should your call take longer than 5 seconds to process the API will provide a 307 Temporary Redirect URI. This 307 redirect can only be called with GET calls. You can learn more about this in the “Jobs” section of this guide.
You will want to periodically check the status of your job ID to determine if your call was successful or still in progress. We recommend running a GET call against this redirect URI in 1-5 second increments. The call will either provide the same redirect URI with an “incomplete” status or provide the applicable output once complete. You can view the call in question here.
PUT is utilized mainly for update capabilities. A successful response code would be 200 and an unsuccessful one is 404. This would be from not returning any content in the body from a PUT.
Once you have the record IDs, you can adjust the TTL with a PUT command to update the TTL based on the argument that you make. The guide can be found here.
Below is my demonstration:
DELETE is simple to understand. It is utilized to delete or remove a resource identified by a URI. On a successful deletion, return HTTP status 200 (OK). An unsuccessful response code would be 404 (NO CONTENT) with no response body. An example would be such below:
After you make the proper modifications to all of your records, you will want to publish the changes and then close your session. When a user is ready to make their changes live, they just need to call the Publish command. After making the Publish call, you will then see the updates appear in the UI. Additionally, all pending changes for a zone go live when the publish request is made. The Publishing instructions can be located in this help guide.
Below is my Publish example:
Note: The publish uses a boolean true/false and not a string value.
The last thing you should always remember after your changes is to log-out from your session. Instructions for making the Log-out call can be located here.
For more API status code, you can visit this help guide.
Finally, to prevent any abuse of the service, Dyn’s Managed DNS API has a set request-rate limit that controls the number of changes you can make in a certain time window. The default rate limit is currently 300 requests per minute or 5 requests per second. This limit is cumulative across all users within an account. During the rate limiting time frame, all new API requests account-wide will receive a “429 – Too Many Requests error” for up to sixty seconds. Once this expires, any users within the account can attempt to make a new request with the same session/token. Rate limiting only affects new, inbound API calls; it does not halt existing jobs or interrupt/delete active sessions. As user or developer always consider pull/manipulate date in the most efficient way. For more information in regards to Managed DNS API rate limit, check out this guide.
I hope the information provided above regarding API is helpful. To learn more about API and to explore various calls, please visit our Developer Resources page here. Have fun exploring API and making your actual calls!