Kaboom – And then there was APIs! Lets get right into it and get this DEVASC passed!!! 🙂
Northbound vs Southbound APIs, Synchronous vs Asynchronous, Authentication types!
API (Application Programming Interfaces) allow Applications to talk to software to perform various tasks (configure / read / delete resources), the most common of these for DevNet exam day will be Northbound and Southbound APIs, so we better know them!
Northbound vs Southbound APIs
As illustrated above Northbound and Southbound APIs are really centric around the Network Controller, as the Northbound API will be RESTful (secured via TLS) for network Admins to make changes via some sort of Application or Web GUI, which then communicates these changes to the Network Controller (still in a Northbound way from Controller to GUI).
Southbound APIs are used between the Network Devices such as Routers / Switches / Wireless APs / any network devices, to not only configure them with traffic routing and security policies, but also to perform many different operations like Telemetry for DNA Center or SNMP like operations using NETCONF or RESTCONF.
***One take away is that Southbound APIs do more than just configure devices at the Data Plane, however that is their primary function, it is not the ONLY function!***
Synchronous vs Asynchronous APIs
When speaking about APIs, we are talking about how they work within an Application.
Synchronous APIs in an Application means that the API call must be returned before the Application can proceed with its function, meaning it can cause the Application to crash, which means that it is generally attributed to a poor user experience.
So why even talk about Synchronous API calls at all? Good Question!
If a resource that is being called is being utilized by multiple elements / does not have the underlying CPU / Hardware resources to store thousands of Asynchronous API calls, then a Synchronous API Call to that resource would be more appropriate.
Which brings us to why to use Asynchronous API Calls – Better User Experience! The Application can make the API Call and continue on with its function while awaiting the call back, assuming the resource returns back a good (2xx) response back to the API Call.
The Take-Away = Applications will use Synchronous APIs if the resources being called are under a lot of stress / lack hardware resources to power them, where Applications using Asynchronous API Calls will continue processing functions while waiting for API Calls to be returned and crash less – Making Asynchronous much more prevalent in Applications.
(Representational State Transfer) / REST / RESTful APIs
REST APIs are also considered a RESTful API, because they are structured in a way to use HTTP Verbs that allows them to be vendor / software neutral, these verbs allowing them to perform the same operations against Websites and Servers alike as shown below:
NOTE – HTTP VERBS ARE USED IN API’S WHILE CRUD IS USED FOR DATABASES!
You will not use “create” or “read” in an API, however the mapping is essentially the same.
One thing to point out is Patch in API use, as its explained in some documentation as a “partial update” while in others it is referred to as “appending” information!
^^^ That kind of mixed definitions depending on the source is something to watch for on exam day as you may use one study material, and not realize it can also “append” data.
Shown above is an Application called “Postman” that is a free GUI Application to make API Calls to different resources, which here I do a “GET” to the “Internet Chuck Norris Database” to retrieve a “Read” resource that is returned in JSON formatting – Which most notably shows the “Success” response of “200” OK which is what we want to see.
The Takeaway = These HTTP and CRUD functions are both important to know for exam day not only for what they do, but also how they work in testing, and I fully expect to see this used in some Python format of API call on exam day – Which will be explored!
(More to come on Python API Calls and response codes in a later post)!
RESTful API Authentication / Authorization
API’s will generally have at least Authentication which is WHO you are, while it may also have Authorization which is WHAT you can access once Authenticated, as once an API is Authenticated / Authorized to a resource it can POST / DELETE / PUT / PATCH (Configure) the resource it is accessing.
For that reason, and for the DevNet Exam, we need to know our API Authentication!
Basic Authentication / Base-64 Encoding
The two big issues with this type of Authentication is that credentials are in clear-text or encoded using base-64 encoding (which takes a google search to decode), and it is passed back and forth every request in the API Header, so possible attackers have more than one chance (as many as you give them) to sniff the traffic and capture the credentials.
Basic Auth can be secured when used with SSL or TLS, but the least secure by far.
API Keys
API Keys are pre-determined keys between a Client / Server as shown in Meraki Dashboard:
In this scenario this is my home Meraki Network which created the API Key String (being the Server), which I would then use myself or provide to other trusted developers, that could then be used to make network changes – This API Key IS the Authentication / Authorization.
This API Key can be passed to the Server from the Client in 3 different ways:
- String = loopedback.com/secret_vault?api_key=SuperSecr3tKey4Ap1!!
- Request Header = X-API-Key: SomeAPIkey123456 (in a program like Postman)
- Cookie = Cookie: X-API-KEY=SomeAPIKey1234!!!
These are rough examples of how to transmit the API Key, as these can be used via Python scripting / an Application like Postman / a Webpage with the URL properly formatted.
More on that to come but that is the million foot view of API Keys and their usage.
Custom Tokens
Custom Tokens are generated by entering a users credentials which in turn creates a custom token once Authentication / Authorization is confirmed, the idea of a custom token is that it eventually expires at set intervals of time, forcing the user to re-authenticate occasionally.
This token reduces the amount of times that Authentication is needed, making the login process to access privileged resources smoother, the token is stored within the web browser or program accessing the resource via API until it expires or is destroyed via logging out.
The Takeaway = First the credentials are Authenticated, then a unique token is generated from the Server, and passed back to the Client that stays valid for a set amount of time.
(Simple Object Access Protocol) SOAP API
SOAP is notable unique in the ways that it commonly uses HTTP for Transport to Web Services, though it can also utilize SMTP, and it specifically uses XML for data transport and communicating with Web Services that use Java / PHP / .NET / Etc.
SOAP is Operating System Independent so it works on Windows / Mac / Linux which makes it a great Intermediary API for Clients and Server, along with the fact the XML has extensive Libraries to work with it, though SOAP API Messages do need to consist of some specific items.
These items consist of 3 main components and 1 optional component:
- Envelope
- Header
- Body
- Fault (This one is optional)
This is a logical view of what a SOAP API looks like, with the “Envelope” containing the XML Data with Headers and Footers (beginning and end) of the XML Data Formatting indicating it is a soap message, then is followed by one or more Headers and then a Body which contains the Data Payload of the API Data (SOAP messages must contain at least one Body element).
One important note – SOAP will generally automatically create the Headers to Client Nodes from the Web Server or API Resource in response to a request, so if you are seeing a SOAP Header it can generally be thought of it being a response to a SOAP API Call from a Server.
Below is what a SOAP API Envelope / Message looks like created in Visual Studio Code:
What this does not show is the “POST HTTP 1.x” in this example, which is NOT the same at the XML v1.0 seen here, it is the SOAP Version # that is used for the API Call.
The World Wide Web Consortium / W3C recommends using SOAP v1.2, though a SOAP node is able to support both v1.1 and v1.2 of SOAP API Calls, the preferred is v1.2.
What IS shown here is the “Optional Fault” field, which these two lines are REQUIRED to be in this Optional section if it is part of the SOAP Body, so to really emphasize that “faultCode” and “faultString” MUST BE INCLUDED IN THE OPTIONAL FAULT FIELD!
A quick review of Fault Codes that might be received and what they mean:
- Sender = The message was not properly formed and could not be understood by the receiving end, namely some element within the message did not match the envelope
- Receiver = The message was not processed for a number of reasons on the remote end such as unreachable or unavailable resources, but is not a sender or format issue
- DataEncodingUnknown = A Header Block or Child Element in the SOAP at the faulting node or remote node is “scoped” (not readable by receiving node)
- VersionMismatch = Faulting node received invalid elements within the Envelope other than expected, most likely the “namespace” or “localname” is needed to be changed
- MustUnderstand = This is specific to a child element in the SOAP Header, if triggered it means any information sent with this message was not understood
I am a little iffy on including all that info as it seems a bit overkill to know for SOAP API, but I’d definitely know those two values “faultCode” and “faultString” that MUST be included if there is a fault field included in the body of a SOAP Envelope.
Remote-Procedure Call (RPC)
An RPC is a fairly standard part of a system process in any network environment, when running a process it will use an RPC to make an API Call to GET or POST to a remote resource as though it were being executed locally, and is “Synchronous” in the way that the Client is blocked from continuing processing the request while the RPC is being processed to ensure a bad actor does not use a systems RPC to flood a resource like a DDOS attack.
For example Multi-Factor Authentication will generally use an RPC call to the MFA Vendor resource to connect to a Client VPN, and if a bad actor got ahold of credentials or a PC with Client VPN access, they could flood VPN Requests / MFA Pushes to DDOS the MFA Access.
There ARE Asynchronous RPC Calls as well, I won’t go into those, but they do exist.
Below is an example of an “XML-RPC Call” I found on a fellow wordpress blog:
This image is courtesy of this wordpress blog: https://cm-wp.com/wordpress-xml-rpc-remove/
^^^ I have nothing to do with that blog, but great example, and also has some good additional content on RPC calls that is good reading, however I won’t go much further into them beyond just knowing that formatting of “methodCall” in XML = An RPC Call.
With that I will end this post here, as the next post will be more in-depth API info!
Next will be a focus on REST API in depth including HTTP Response Codes, Constraints, Headers, Authentication, Communication, and bringing Python back into the mix to see how it can be leveraged to make RESTful API Calls and receive return codes for testing!
Until next time!!! 🙂
The DEVNET GRIND! 