Intro to APIs
API = Application Programming Interface, APIs define how users / developer / other applications can communicate with each other, API’s will generally use web-services or web based communication however they can use unique protocols for proprietary APIs.
API’s not only provide communication, but also secured communication by several different methods, and all services / components / databases of an application are accessed via the API so if the API cannot see it no end users or applications will see it.
Some common API use cases can be as follow:
- Automation – Writing scripts that automatically perform tedious manual tasks
- Data Integration – In the way that many online retailers have PayPal integrated into their website as a Payment Processor
- Functionality – The way that Google Maps might integrate location services into Google Maps to not only give directions, but the best possible directions at that time
API Design / Delivery style : Synchronous VS. Asynchronous
The two different designs of API Design will respond differently in how it handles requests, so below I will run through the differences between them.
Synchronous
This style of API allow the application to receive data immediately, it works on a first come first serve basis where if the resources are readily available it responds immediately, for this reason Synchronous APIs are the most commonly used.
Software using Synchronous Design must wait for the API requested data to proceed executing, as it is “designed” to have that data moving forward with the execution
If not designed properly the API may create a bottleneck because of this first come first serve model, which is a potential drawback with this API Design.
Asynchronous
This API type will not respond with request data right away, but will respond acknowledging the request was received, and then triggers a “Callback” to send the requested data once the server or host can process the request. Though it is not guaranteed the data will not be immediately returned, the data CAN be immediately returned if readily available.
Software / Applications using Asynchronous APIs can continue with execution without getting the API immediately returning requested data, therefor may have better performance, however if excessive Asynchronous API Calls are made this can have the opposite effect of creating a delayed response / bottleneck for the remote API resource.
One important note of Asynchronous API Calls – The client will dictate to the remote server whether it needs a response ASAP or may require a queue to store the data to maintain the correct order of data processing / find out the status of the request.
API Architectural Styles – RPC, SOAP, and REST
Below are detailed description of the three major API Architectural styles:
RPC – Remote Procedure Call
RPC is a Request – Response Model where the Client is the “Caller” to the remote resource such as a Server which is the “Responder” or “Callee” which is typically located within the same Network or LAN.
The Client is unaware of the underlying Remote Procedure Call being made to the “Callee” or Server, as it is just executing some type of function that makes this call, and then waits for the Response from the server with the Data to continue or finish executing the function and move onto the next process or function.
Most commonly with RPC the client will halt its local process and make a Synchronous API Call to the remote Server / Resource, and the process will remain halted until the data requested is received back – This does not apply to Asynchronous API calls.
In a real world example, you might see issues with applications having an RPC Error if its “Callee” or Server is hosed up / hard down / unreachable on the network.
RPC can be used with many different Transport Protocols including:
- NFS (Network File System)
- XML-RPC
- JSON-RPC
- SOAP
Speaking of SOAP, lets speak about SOAP!
SOAP – Simple Object Access Protocol
SOAP is a messaging protocol that is used for communication for applications that may reside on different platforms or built using different languages, it is an XML-Based Protocol (which XML has “Legacy” support for SOAP of the 3 Data Formats on the DEVASC exam!) and is commonly used with HTTP, though it can work with other transfer protocols as well.
SOAP has 3 major characteristics described below:
- Independent – SOAP was designed to communicate with any type of application, regardless of language its written in, OS its hosted on, its completely flexible
- Extensible – SOAP is considered an application of the XML, which means extensions can be built on top of that which can add features like reliability and security
- Neutral – SOAP can be used over any protocol (HTTP / SMTP / TCP / UDP / JMS)
SOAP Messages
A SOAP Message at its base is an XML Document that includes 4 elements:
- Envelope – The envelope must be the root element of the XML Document to define that when the Document is processed it is recognized as a SOAP message
- Header – This is an optional field for Authorization / other Attributes, but if present it must be the next line down from the “Envelope” beginning line of the document
- Body – This contains the Data to be transported to the recipient and must be in XML Format (again XML has “Legacy” support for SOAP
- Fault – This is also optional, but must be a child Element of the Body which will provide any error or status information
To visualize the formatting of this message, I’ve created this small demonstration:
They of course get larger / more complex, but this gives a small demo of a SOAP API Call.
REST – REpresentational State Transfer
REST API’s are defined as a Hybrid Style API derived from network based architectural styles with 6 constraints that define a uniform connector interface (to be consumed):
- Client-Server – The client and server should be completely independent of each other, allowing the Client to be built on multiple platforms and simplifying API Components on the Server side of things
- Stateless – Requests from the Client must contain ALL information the server will need as the server will not maintain a stateful connection to receive this info
- Cache – Responses from the server must contain whether they are cacheable or non-cacheable so the client can use the same data in later requests to that server
- Uniform Interface – This will be broken down into four principles below
- Layered System – Hierarchical layers in the system that allows for logical layers that will only provide services to the layer above it, reducing resource consumption
- Code-On-Demand – This is an optional constraint because “Code on Demand” refers to the information a REST API my send in its response can contain 3rd party executable code or links to 3rd party code, which some firewalls will now allow
These 6 Constraints are what makes up a RESTful API, and work with ANY protocol.
The 4 principles of a Uniform Interface between a Client / Server:
- Resource Identification – A specific resource must be identified in an API request as the object that the server or resource will manipulate, which can be a single object like a file / image up to one specific object that contains a collection of objects
- Manipulation of resources through representation – The client receives enough data or metadata from the server of the resource that it can use for manipulation, this can be an exact copy of the resource or a simplified version of the data, it cannot just be an identifier to some other / additional resource (must contain data)
- Self Descriptive messages – Messages must contain information for the recipient to process the information such as Protocol Type, Data Formatting, and requested operation or function to be performed
- Hypermedia as the engine of application state – The data sent by the server or resource must include any additional actions or resource for the client to access any supplemental information for the requested resource
So to review that in human terms:
- The client must specify the exact resource the need
- The server provides the data requested that is required to fulfill the request
- Each side must provide full information required to communicate with each other
- The Server must include any additional resources available
Like going to a meme generator website and filling in the information for a meme (#1), the website calls to its database to get data to fill in the funny meme (#2) by the Website and its LOL Database identifying all info for communication and encoding / encryption / data formatting / etc with each message transmitted (#3), and the server will likely recognize it is generate a hilarious meme and include a “Create another meme” or Links to the webpage (#4) so you can share the hilarious meme on Twitter!
Intro to REST API’s – A deeper dive
How REST APIs at a high level view work, is that a client sends an HTTP Request to a Server or Resource, that the sends an HTTP Response with the data requested back to the Client to then process within its application or software as illustrated below:
Client ——Request—-> Server
Client <—-Response—- Server
The first type of API to dig into is the Web Service API as that is by far the most popular type, which uses the 6 principles for a REST API described just above (Client-Server / Stateless / Etc), and most of them will communicate using over HTTP by using the same concepts of communication for HTTP such as:
- HTTP Verbiage – Mapping showed below from Verb or Method to Action
- HTTP Request / Response
- HTTP Status Codes – Like how “404 Webpage not Found” means the resource is not available both for the website, API’s use this code if the Resource is not available
- HTTP Headers and Body – Contains communication information and data payload
REST API’s work almost exactly like an HTTP Request in a Web Browser, but are made up for 4 major components that you must know like the back of your hand for exam day:
- Uniform Resource Identifier (URI)
- HTTP Method
- Headers (Optional)
- Body
The URI – Uniform Resource Identifier
A URI is so similar to a URL (Uniform Resource Locator) is made up of 4 components:
- Scheme
- Authority
- Path
- Query
Similar to using the search function on my website, I get the following URL:
https://loopedback.com/?s=devnet
Scheme indicate which HTTP protocol is being used, of which there are two, HTTP which is not secure, or HTTPS which of course is Secured.
Authority consists of two components: The Host and the Port, which the out can either be a FQDN or IP Address while the port is either 80 (HTTP or 443 (HTTPS) unless unique.
Path in this example is literally just “/” in the Web Address.
Query in the example is the ?s=devnet which is indicated by the “?” and the Query or Filter will follow, in this case it is “Search = denvet” or “s=devnet”
Using HTTPS I ran a Query against the Authority loopedback.com with no specific path to the resource specified (however with an API you will generally have an actual Path), and I get a webpage returned to me filled with all my articles with the keyword of devnet.
Though what is shown above is a URL, a URI will have the same format except it may be something like:
https://145.20.53.181:8080/api/resources/?r=somefile.txt
This is using HTTPS Secure “Scheme” and the “Authority” 145.20.53.171:8080 (using a unique port for communication), with the “Path” being /api/resources/ being the path to the resource requested and and ?r=somefile.txt being a “Read” Query being run against that Authority / Paths Database for “somefile.txt” to show the formatting of a URI.
Okay, no more colors, moving on!
HTTP Method to Action Mapping and Description
Below is a quick mapping of the main HTTP Method / Verb to CRUD / Action Mapping:
This is what you might use if you are using “curl …” from a Bash prompt to send the HTTP API Call, or whether you are looking at Postman HTTP API Call software, there are several more but these are the main ones to no absolutely for the DEVASC exam and fundamentals of working with APIs in general.
API Header(s)
Headers in APIs are formatted the same way as an HTTP Header, and although this information is optional, if needed for a specific API we need to know the difference between the two different types of API Headers available for use.
Headers use a name:value or key-pair formatting like as used in many data formats.
The two API Header types:
- Request Headers – Includes additional information relate to the content of the message itself, such as an Authorization value in a Request if one is needed
- Entity Headers – Includes additional information describing the data contained within the body of the message, such as Data Type / Formatting
Request Header Format:
Key | Value | | Description
Auth – wiefiIUSEF87743w – Provides Creds to authorize request
Entity Header Format:
Key | Value | | Description
Content Type – application/json – Specify format of data in Body
Again although this is an optional field (and maybe no so option when it comes to Authorization) it is very important to know both types of Header for exam day!
API Body
The body contains the data from the Resource that the Client wants to manipulate via an HTTP POST / PUT / GET, for example if you test this with a URI that provides Chunk Norris jokes either via “curl get https://api.icndb.com/jokes/random” command in Linux Bash prompt or how I do it as shown below in Postman:
This will return a Chuck Norris joke from the “Internet Chuck Norris Database” website, which is a fun way to play with API Calls using Curl or Postman, though I use Postman so I can look at all the different Parameters like Headers, Cookies, change Data Formats, etc.
Postman uses JSON formatting by default for the body, however you can change between XML / HTTP / Plain Text (they all look basically the same) whereas by default I believe Curl from a Linux Bash will return the data in the Body of the message (the joke) in one line using HTTP Data Formatting for its output / data manipulation.
REST API Responses – Status Codes / Header options / Body details
The first thing to review in this section will be the Status Codes from a Servers HTTP Response to a Clients HTTP Request, as when a Client sends an HTTP Request it is POST (Create) / GET (Read) / PUT (Update) / Etc, the HTTP Responses from servers will return Status Codes that indicate how the Request was processed.
An example of this is the Classic “404 Webpage Not Found” back before every domain was bought by Web Hosting companies and now you get “Domain for Sale” instead 🙂
HTTP Status codes – 3 Digit codes returned to Client HTTP Requests
- 1xx = Informational – Information purposes only, that the server received the request, generally won’t contain data in body of response, Client can expect a follow up response at a later time
- 2xx = Success – Server received and accepted the request, for Synchronous APIs the response will have Data in the Body of the Response, for Asynchronous APIs generally will not have Data in the Body of the first response but is processing it
- 3xx = Redirection – The Client must provide additional information, which is generally a different (correct) URL / URI needs to be used, or the Client might be automatically redirected without manual intervention by the Client
- 4xx = Client Error – Request contains an error such as a Syntax error or invalid input which is prevent the request from being processed, requires a manual fix on the Client side to complete the request
- 5xx = Server Error – Server is unable to fulfill the Client Request BUT THE REQUEST IS VALID(!), depending on exact code Client may want to retry later
Below is a more specific list of exact codes and what exactly they mean:
Status | Code | Description
200 – OK – Request was successful and typically contains Data in Body (Synchronous)
201 – Created – Request was fulfilled and the resource was Created (POST)
202 – Accepted – Request has been accepted but not yet fulfilled (Asynchronous)
400 – Bad Request – Request not processed due to error with Client Request
401 – Unauthorized – Request does not have valid Authentication Creds for Reqest
403 – Forbidden – Request was understood but rejected by the Server
404 – Not Found – Resource Path from Request not found on Server from Request
500 – Internal Server Error – Request cannot be fulfilled due to a Server Error
503 – Server Unavailable – Request not fulfilled because Server cannot handle the Request
HTTP Response Header – Also optional, also uses key:pair values, also provides additional information to the Response provided by the Server to the Client
There are also two Header Types for HTTP Responses, one is the exact same:
Entity Header Format:
Key | Value | | Description
Content Type application/json – Specify format of data in Body
Response Headers Format (Yes they are actually just called “Response Headers”)
Key | Value | Description
Set-Cookie – JSESSIONID = EIi349Sbf77SE;Path=/ – Used to send cookies from the Server
Key | Value | Description
Cache-Control – Cache-Control: max-age=600, private – Specify directives which MUST be obeyed by any and all Caching Mechanisms in the application / Requested information
Big take-away from HTTP Request and Response Headers – They are optional, however the Request will generally be used for Authentication, and the Response will generally tell the Client how it will be provided information by the Server
If you see Authentication, you are looking at a request, if you are looking at Parameters being identified for communication your looking at a Response Header.
HTTP Response Body
This is where the Data goes, although this IS OPTIONAL due to all the different types of requests, so if asked on exam day if an HTTP Request Body must contain Data the answer is NO! However, if there is Data in the Body it is usually defined by the Content-Type key parameter set in the Header.
If an API Request is Unsuccessful for any reason, the Body of the Response may have details as to why the request failed or was denied.
Response Pagination
Quite the word, Pagination, I am not even sure how to pronounce that.
This essentially means when I use the search function on “loopedback.com” to search for the key word “devnet” and it finds 50 articles, Pagination enables this giant amount of data to be broken up into chunks of data, so instead of all 50 posts I might get 10 posts per page rather spraying all 50 posts on the page.
You can also define more specifically which chunks you are looking for like “devnet GIT” in the search function to further narrow this down, or however else it can technically be done, but that is all I am really going to commit to memory about Pagination 🙂
Compressed Response Data
If Data cannot be Paginated and the Request requires a giant chunk of Data, Compression is performed on that data, which requires an Accept-Encoding parameter in the Header.
The accepted compression values for HTTP Responses are:
- gzip
- compress
- deflate
- br
- identity
- *
If the data does not get one of these in the HTTP Request, it will return a “406 – Not Acceptable” Status Code, however if an acceptable format is Requested the Response will include a Content-Encoding field in its Header indicating the type of Compression performed so the Client know how to properly decompress the data.
Using Sequence / Event Diagrams with REST API
Sequence AKA Event Diagrams for REST API is a way of modeling or describing the flow of a sequence of events that must take place to accomplish a task, as you generally cannot just do a “GET” request to a completely open / public Resource, as demonstrated with the Chuck Norris Jokes API Call – There is Authentication and several other tasks that may preclude the end goal of your Automated Task of Reading or Writing something to a Server Database which is what a Diagram is for.
It is similar to UML (Unified Modeling Language) formalized sequence diagrams that clearly and visually explain a flow of events, including interfaces / protocols / objects / resources / etc that are in the flow, and the sequence of events that leads to the end.
To demonstrate this I’ve reverted back to what I know – Meraki API Integration:
This more or less visually explains the flow or purpose of Sequence Diagrams to visually understand the flow required for a task to be completed via API calls, though this is far from complete – The Client itself could be a PC running a Python Script or using Postman to send API calls in a certain order and the Server could be a Meraki Portal / Apache or NGINX Server.
This will generally include much greater detail such as Protocols / exact paramaters / etc but this is just a quick mock up of a simple visual demonstration.
All things REST API Authentication / Authorization
There are some API Resources that do not require Authentication which will generally be Read-Only, for example doing a GET to public API Resource https://api.icndb.com/jokes/random for Chuck Norris jokes that does not require any Authentication.
Authentication vs Authorization
Authentication is the act of proving your identity, while Authorization is the act of providing proof you are allowed to access the resources you are attempting to access.
3 REST API Authentication Mechanisms reviewed
- Basic Authentication
- Bearer Authentication
- API Key
Basic Authentication (Basic Auth) is the simplest Authentication of the three types, using Base64 Encoding which can be found at this URL: https://www.base64encode.org/
^^ At this website you can type in ‘Hello World!’ and get ‘SGVsbG8gV29ybGQh’, however you can also click “Decode” and input that same encoded chunk of text, and it will output ‘Hello World!’ – So it is not Secure unless using HTTPS!
If sent via HTTP Basic Auth / Base64 Auth is completely unsecured as it just makes a Username / Password a blob of text that is easily decoded, unless paired with HTTPS which will use SSL Encryption for the request.
Bearer Authentication / Token Authentication
Bearer Authentication is AKA Token Authentication which uses a “Bearer Token” which is a string generated by an Auth Server or IdS (Identity Service), it is more secure because it is typically paired with OAuth or SSO (Single Sign-On), but should also be sent using HTTPS to use encryption for enhanced security.
The header of the REST API Request will need to include:
Authorization: Bearer <token>
Again though this is more secure than Base64 or Basic Auth even without pairing with OAuth / SSO, it is very unsecured using HTTP in the REST API Request!
API Key / API Token REST API Authentication
An API Key is also referred to as an API Token, and this API Token is an alpha-numeric string generated by the Server and provided to the user / Client generally by logging into some type of Portal with credentials to obtain said API Token.
As with all Requests, HTTPS is the only way to truly secure the payload with Encryption.
There are two types of API Keys / Tokens: Public Keys and Private Keys.
Public API Keys are meant to be shared to a subset of users / Clients to access a Resource, while Private API Keys are like your Username to log into your company computer, you do not want to give it out to ANYONE or it will have your username associated to any actions taken with it if it was securely provided to you.
Given that API Keys generally do not have an expiration date once they are created (although they can be changed / removed at any time by the Resource / Server), anyone can continue to access that system with your identity, unless deleted / changed by an Administrator of the resource which can be a real nightmare depending on how many systems are tied to a single API Key – So even Public ones should be very limited in who it is shared with.
There are several ways a REST API can provide its API Key in the request:
Adding it to the Resource URI in the Query Parameter:
GET https://loopedback.com/somepage/api/examples/?API_KEY=(API_KEY_HERE)
Adding it to the API Request Header:
Authorization: <API Key> or Authorization: APIkey <APIKey> or APIkey: <APIKey>
^^^ Any of those formats in the Request Header will work!
Adding it the Body of the Request:
{
API_KEY: <APIKey>
}
And finally as a Cookie using the API Key as the identifier:
Cookie: API_KEY=<APIKey>
In all of these examples, <APIKey> of course refers to the unique API Key / Token.
Authorization Mechanisms for REST API Authentication / Authorization
Open Authorization is what is commonly called OAuth, which combines both Authorization and Authentication, which remember Authentication is proving your identity while Authorization is proving you are allowed to Access a Resource.
There are two versions of OAuth, OAuth v1.0 and v2.0, though v2.0 is more commonly used and important to note that OAuth v2.0 is NOT backwards compatible!
OAuth 2 has a Framework that allows for 3rd party applications to obtain limited access to an HTTP Service either on behalf of a Resource owner and HTTP Service, or by allowing a 3rd party application to obtain access on its own behalf – This is essentially allowing for applications to preregister to get Authorization to perform a REST API Request on a users behalf without need their creds within the application itself.
OAuth is essentially allowing a user to provide credentials directly to something like an IdP or IdS (Identity Provider / Identity Service), allowing an access token to be obtained by the Application that will be sending the API Requests.
This process is called a flow, and the application essentially now uses this API Token just like a “Bearer Token” to send to the Authorization Server to ensure the Token is valid and the Application can perform the rest of its task once Authorized.
Labbing with REST API’s in Python
Reading all the books in a Library in Python:
Script
Output
Adding a book to the Books Python Library:
Script:
Output:
200 OK!
Using the UrlLib Library via Import to make the request much larger:
Output (that I think might have messed up):
This should be a “200” for a Response, however the Python Environment in the Cisco Modules will sometimes glitch, I tested this by just using the copy function from the explanation side of the page to paste the same Syntax and sure enough 200-OK returned.
Doing a “PUT” request to update an authors name in the book collection:
And the output:
Then to DELETE a Book from the library:
And output again is “http status code after deleting the book: 204”
Authentication Python code is shown here using Username / Password:
This is still unsecured as the password is in plain text, output is 200 Response.
REST API Rate Limits
Rate Limits are a mechanism used to avoid Server Overload / DoS Protection / Increased Response Time for requests to Server by limiting the amount of Requests that are allowed in a time-frame, which should be adhered to by the user / Client but can also be gracefully or dynamically handled by the applications when those limits are being hit.
The 4 different Rate Limit Algorithms reviewed
- Leaky Bucket
- Token Bucket
- Fixed Window Counter
- Sliding Window Counter
Leaky Bucket Rate Limit
This request type has a rate limit at which Requests will be processed, how large the Queue is, and any Requests that are past the total Queue value are rejected.
The “Leaky Bucket” describes when Requests come in at an inconsistent rate, the Queue might overflow with Requests, thus ending up with some being rejected from processing.
This type of Rate Limit requires the client to understand how to handle delayed (queued) or rejected responses from the Server.
Token Bucket Rate Limit
This algorithm provides the user with a defined limit of tokens that it will accept from them within a given time-frame, which they can only use the defined # within that time, and once they run out of tokens the Requests will start to be rejected.
So this can be thought of as a Bucket filled with Tokens, and each Request takes one out, and if the bucket is empty Requests are rejected, until the bucket is refilled within a defined amount of time when it will refill with the # of tokens to be used again.
One interesting concept with Token Bucket – Token Bucket algorithms will start rejecting Requests if say 5 are allowed per hour on the 6th request in that hour, but if no requests are used for 10 hours they will accumulate so suddenly after 10 hours 50 Tokens have accumulated and can be used in rapid succession (more than 5 per hour) until the bucket is exhausted.
That is a fairly unique feature, I’d expect to see that on exam day, Token Bucket = Accumulation of Tokens!
Fixed Window Counter
Unlike Token Bucket, this algorithm will not accumulate more requests within a time period than defined, because it does not use “Tokens” as its limit, but rather a window of times is issued a counter to represent how many Requests can be issued during that time.
For example, say a CLI has an exec-timeout of “30 seconds” and the SSH connection is closed after 3 failed attempts – If you only try once before the sessions times out that does not mean you can get 5 login attempts the next 30 second SSH Login prompt.
It is very close to Token Bucket, however it works within a limited time frame, and it doesn’t accumulate.
Sliding Window Rate Limit
This is essentially “throttling” the amount of requests by having a repeating Time Window with a set counter that limits the rate of requests as well, but there is no defined start and stop time of the Window – However it will only allow X Requests of X minutes.
As long as the user / Client / Application knows the rate limit, it can steadily send requests at that rate without getting them rejected, and there is no minimal limit / accumulation as well with this method.
Applications must also be able to know how to handle rejected Requests with this method as well, or have a built in and understood limit that it sends requests at.
Knowing the Rate Limit
API Documentation will include Rate Limit information in both the rate limit and unit of time it uses in a key : pair format, with some of the formats in the header being:
- X-RateLimit-Limit – The Max # of Requests made within the unit of time
- X-RateLimit-Remaining – The # of Requests left for the current time unit window
- X-RateLimit-Reset – The time when the rate limit resets
If the Rate Limit is exceed common Response codes will include 429 : Too Many Requests or 403: Forbidden, and these may be specific to the API in use.
API WebHooks – Working with them and what they are used for!
A Webhook is an HTTP Callback / POST to a specified URL or Logging Server that is triggered when an event occurs on a platform, similar to how Meraki has “Alerts” that email Admins and any other specified emails if an event happens you can also use Webhooks to trigger an Alert.
Webhooks are known as Reverse APIs, because the roles of Client and Server really are reversed, as during a registration process with a WebHook Server the application provides a URI to be called by the WebHook server when the event triggers an API Call.
When the event is triggered the Webhook Server initiates the API Call by sending the Notification to the Application / Client to the provided URI, and the Application will then receive the API Call (POST) then respond with a Response Status to the WebHook Server with (hopefully) some type of 2xx or more specifically 200 OK Status Code that it was received.
A couple of things I wanted to post here for reference is the Meraki API Setup that you can Enable in the “Networks” of an “Organization” (Where an Org is a collection of Networks within that Org, and each Network has its own Firewall (MX) / Switches (MS) / Wireless APs (MR) within them), and this is at the Network Level within my home Org:
This is in the “Network-wide -> General” page in Meraki Dashboard, there is also a section for this under “Organization -> General” at the bottom of the page to Create a unique API Key called a “Fingerprint” to provide to other applications to call to this network for information. here is a picture of that along with the “profile” :
First you Enable the API Org-Wide so it has full access to all Networks and other pages such as “Licensing” to check that your Licenses are not coming up for Renewal or Inventory so you can GET a copy of what Devices are Claimed to what networks and correlate that with Licensing to ensure you are not paying for Licensing on unused devices as Meraki Licensing is not cheap (No offense to Meraki intended).
First you go to Organization -> General settings to Enable API Dashboard access:
Enable the API on Org-Wide and Save, then click the Profile hot link which will jump to your Admin Profile page you are currently logged in as, which you then create what is called in the Meraki or maybe just real world IT Circles a “Fingprint” or “Thumb print”.
This is done in your admin profile page by creating a new API Key (fingerprint):
Then once this is saved, it will show the last 4 of your Key / Date Created / Last use:
This is completely off the topic of Webhooks, but while I was in my dashboard I saw this, and thought it was worth posting as a refresher to me and for anyone who hasn’t seen a Meraki Dashboard before, it is all navigated via left Side-Bar that break out into options:
Network-Wide is for things like Logging, Packet Capture, more passive configs like SNMP, Security & SD-WAN will be your Firewall Settings (MX) where you can do Traffic-Shaping / ACL’s / Layer 7 Content Filters / Etc, Switch is pretty straight forward though the actual Switch pages for Switches and Switchports give excellent troubleshooting information, and here I show the Wireless options (I never knew there was an IoT Radio Settings in there until now!), and finally Organization is where you’d handle Licensing / Admins / Creating Networks / Inventory of all Network Devices / Etc. so its the Top Level Category followed by Networks which will then contain the MX / MS / MR pages for that Network.
Now that I have completely derailed from Webhooks, back to that!
Here are the Meraki Dashboard Webhooks from my own home Dashboard:
And to visually demonstrate what it looks like when adding a Webhook Server:
Its a bit small but you can “Name” your Webhook server, provide the URL that the HTTP Request will be coming from, and the Shared Secret that the Webhook server provides during registration to that Server for this Organization (and can even test!).
So some pretty cool stuff there, figured that was worth visualizing if anyone has made it this far into this page 🙂
Last item on my REST API Study Cram Session – Troubleshooting API Calls!
Given the above section of Status Codes and understanding the exchange of REST APIs will go a long way, but this isn’t like a generic protocol that can be caught on Wireshark what is happening, you can make a pretty good guess based off error codes or some other Criteria however you will want the API Config Guide and Authentication info the ready to reference and assist with troubleshooting without spinning your wheels.
For Example, what if no Reponse is received for a REST API Request?
A Response to a REST API Request message is not guaranteed a Response at all!
Troubleshooting Client-Side Errors:
That is an important note for exam day and real world uses, that you may simply not get anything back from the Request, which then some start questions would be:
- Has this ever worked before?
- Is the URI in the Request Correct?
If you send a Request to an incorrect URI, there is no Server that can send any kind of response, so one simply will not be gotten at all (unless the server is just offline which may also be a cause for absolutely no response if there is no redundancy for that server).
To test a URI to see if it is valid is by using the following Python script:
import requests
url = “<URI>
resp = requests.get(url, verify = False)
This will tell you if there is any sort of response or Resource that is on the other side of that URI Call by running those commands in a Python Script / Bash shell.
Then some follow up questions may be:
- Is there a VPN that this traverses? Firewall / Firewall changes? Proxy?
- Is there an SSL Cert involved? Is it still valid?
The response will be pretty specific when running that test from Python with the “requests” imported library, they will indicate if a remote host is reachable, it will spell out if the SSL Cert is no longer valid, and will look something like this returned:
“requests.exceptions.SSLError: HTTPSConntectionPool (host= …. host is not responding) / (host= SSL Certificate is no longer valid) / Etc
This is what is called a “Traceback” which provides troubleshooting information for both Client and Server side issues, speaking of Server-Side issues…
Troubleshooting Server-Side Errors:
Once the Client Side is ruled out for having issues, time to check the Server side.
Thing like “Is the API Server Functioning?” can break down into multiple questions:
- Does the Server have power?
- Does it have network connectivity?
- Is there a DNS or Domain change / issue?
- Do the LED Lights on the physical Server show any faults? Reboot? Panic???
You can also perform Tracebacks on the Server which will have a long delay generally before it returns a response, in which you would run the same type of Python script as above and review the Traceback information to determine the issue.
If all else fails, its may come down to contacting the Resource Server Administrator to verify their network is in fact sending Responses (or even receiving them) if it appears to be functioning properly, and kick it back to the client for troubleshooting if other Clients are reaching the Server but not one particular Client.
A closer look at the Response Status Codes (honestly the last topic covered)
To review the different code types before diving in:
- 1xx – Informational (Request received / Continuing Process)
- 2xx – Successfully received / understood / accepted
- 3xx – Redirection (Further action required to complete request)
- 4xx – Client Error (Client has bad syntax / unauthorized / etc)
- 5xx – Server Error (Server unable to fulfill the Request)
There are three steps to take to review these Response Status Codes:
- Check the return code as the output may help script during development phase
- Check the Body of the Response as this will likely provide detailed error messages
- Dig into exactly what the Status Code means if nothing else to at least have a starting point to direct your troubleshooting towards
2xx Success Status Codes
This generally means everything is ok, you will want to verify the details contained within the response to make sure there isn’t anything off, but generally this is good.
4xx Client Side Status Codes
400 – Bad Request – This is generally a malformed packet (VPN not encapping or decapping?) or the syntax is off somewhere in a parameter, such as making a plural in the URI into a singular for examples typing ‘place’ instead of ‘places’ in the URI.
401 – Unauthorized – This means the Server could not authenticate the Clients request, this could include creds like Username / Password or API Token, and also may want to double check the URI as this may cause this as well if you are trying to get authorized for the incorrect resource within the Path / Query
403 – Forbidden – This is saying the Authorization / Client is recognized but simply not allowed due to a permissions level issue for that user, which may require a super-admin role to access that particular resource
404 – Not Found – The Server is not able to find the resource requested by the Client, again will want to check Syntax and verify in the guide or instructions that the Resource URI / Path did not change over time
405 – Method not Allowed – This one is literally just as it sounds, the Server recognizes the request but the Method defined in the Request is not understood or allowed, again check the documentation or instructions (possibly even the Response Header) for allowed Methods to access the Resource properly
406 – Not Acceptable – This error indicates that the Resource doesn’t have a current representation that would be acceptable to the Client, so the server HAS the data on it but cannot represent it in a way the Client is Requesting (check headers)
407 – Proxy Authentication Required – Similar to code 401 (Unauthorized) however this indicates that the Client needs to first authenticate properly to the Proxy Server
409 – The request couldn’t be completed due to a conflict with the current state of the Resource being targeted
415 – Unsupported Media Type – This indicates the Body of the Request is not recognized by the Server (JSON, XML, etc) and needs proper formatting to be understood
5xx Server Side Status Codes
500 – Internal Server Error – This means the Server itself ran into an issue that prevented it from fulfilling the request
501 – Not Implemented – The Server does not have the function implemented to fulfill the request, similar to a Client Side “Method” status code
502 – Bad Gateway – Typically returned by a Server acting as a Proxy or Gateway that had an issue handling the inbound Response coming from an Internal Resource
503 – Service Unavailable – This indicates the Server is temporarily unable to handle the request due to overload or down for maintenance, and will likely work again shortly
504 – Gateway Timeout – This goes back to the Proxy / Gateway Server, this time not receiving a response within a set amount of time from an upstream server
To wrap up this Gigantic look at REST APIs inside and out. some parting words
There is actually a lot of Python scripting based around “import requests” where you can request certain Parameters via Python script to see what the Return Code is, I may circle back to fill these in once I am more versed in Python, but at this point I am in a time crunch / this article is very much long enough not to add screen snips of Python Code for each individual error Code – But if you google “Python Import Request REST API Troubleshooting” I am sure you can find tons of resource for this information.
With that, I am finally done with this REST API Chapter of Class, until next time! 😀
The DEVNET GRIND! 