Learn API development with Rapid API Comics (sketchnotes and fun analogies).

Rapid API Comics

JSON vs XML

Both JSON and XML are data formats used to send and receive data from web servers.
Both play an important role in organizing data into a readable format in many different languages and APIs.

JSON is short for JavaScript Object Notation. 
It: 
 - is based on JavaScript object literal syntax
 - can be easily parsed into a ready-to-use JavaScript object with no library needed
 - is easy to read and write
 - is supported by most backend and modern programming languages

XML
- Extensive markup language that allows creating custom user defined tags
- Manages data in a tree structure hierarchy
- Complex data structure that must be parsed

JSON vs XML: Similarities and Differences

Generally, JSON is considered better than XML

API Versioning

API versioning is the process of making changes and updates to your API. It is an essential part of API management, and a good versioning strategy will allow updates to occur without disrupting the consumer experience. The aim is to steadily introduce new features, avoid large updates, and maintain functioning.

Why is versioning your API important? As an API evolves and develops, you will make changes and add new features. Even minor changes can have a domino effect and impact programs that use your API services. Such changes that could cause problems are called breaking changes.

What exactly are breaking changes? They could be removing a resource, changing a resource name, changing a resource data type, changing data format (e.g. JSON to XML), and more.

When should you version an API? It is considered best practice to versioning an API only when breaking changes are made. Non-breaking changes alone do not require versioning. Instead, they can be included in more major updates.

The first versioning method is called URI path versioning. With this method, the API version is included in the URI as v1, v2, v3, etc. This method is widely used and straightforward to implement, but it's important to keep previous versions active after new ones have been introduced.

The second method is query parameters. Similar to the URI path, the version is included in the URI, but as a query parameter. This method allows the version to be requested at the resource level. If no version is specified, you can default to the latest version.

The final method we'll look at is custom headers. In this method, the URI remains unchanged and the version number is set using a custom header in requests and responses. You can use the 'Accept-version' header followed by the version number.

Whichever method you choose, it's important to allow backward compatibility. This means keeping previous versions active not only as a backup in the case of breaking changes but also for users who decide to update in their own time.

HTTP Status Codes

HTTP Status Codes are three-digit codes that are returned in server responses to HTTP requests. Status codes tell the client about the status of the request, whether it was successful, and what the problem is if there is one. Understanding status codes is very helpful as it allows you to quickly diagnose errors. Some status codes even greatly impact SEO and the search engine's ability to crawl your site's content.

As a reminder, this is the basic structure of an HTTP response. You'll always find the status code in the appropriately named status line.

There are five groups of status codes to know about. These are 1XX, 2XX, 3XX, 4XX, and 5XX. Each group represents a different type of response from a server.

Starting with 1XX. These are informational responses. They are rarely seen because they are issued when a request is being processed and not in the final HTTP response. As an example, Status code 100 'Continue' indicates the request is being handled and the client can continue.
 
The next group is 2XX which indicates successful responses (the server delivered the expected response). For example, status code 200 'OK' indicates a perfectly successful request. Status code 201 'Created' indicates a successful request where a new resource was created. This is typically a response to POST or PUT requests.

3XX responses indicate redirection is required. The resource or page requested was found, however, not at the expected URL. Most redirection responses include the actual URL the resource was found at, which should be used to make future requests. As an example, 302 'Found' indicates the URI has temporarily changed and may change again in the future.
 
4XX codes are for client-side errors. They indicate the resource/page could not be found. This could be due to non-existent resources, unauthorized clients, or too many requests. 400 'Bad Request' means the request was invalid, and 404 'Not Found' means the requested URL is not recognized.

The final group is 5XX. These are server errors. They can occur if the server is down for reasons such as maintenance or too much traffic. They can also indicate unknown server problems. 500 'Internal Server Error' indicates an unknown server error, and 503 'Service Unavailable' indicates the server is temporarily down but will return to functioning later.