Skip to main content

22 posts tagged with "API"

View All Tags
← Back to the liblab blog

We're thrilled to announce a significant update to our SDK documentation generation: Markdown support is here! This new feature is designed to make your documentation more readable, more engaging, and easier to write. Whether you're a seasoned API developer or just starting out, Markdown can simplify the way you create and maintain your documentation. Let's dive into what this means for you and how you can leverage these new capabilities.

What is Markdown?

Markdown has become the lingua franca of the web for writing content. Its simplicity and readability make it an excellent choice for writing documentation. Unlike HTML or other markup languages that are often cumbersome to write and read, Markdown allows you to format text using plain text. This means you can create headers, lists, links, and more, without taking your hands off the keyboard to interact with with tags or styling buttons.

For those unfamiliar with Markdown, it's a lightweight markup language created by John Gruber and Aaron Swartz. Markdown enables you to write using an easy-to-read, easy-to-write plain text format, which then converts to structurally valid HTML (or other formats) for viewing in a web browser or other platforms. This makes it an ideal choice for writing online documentation, as it's both human-readable and machine-convertible, ensuring your documentation is accessible both in raw and rendered forms.

Supported Features

Our SDK documentation generator now supports the following Markdown features:

  • Headers: Structure your documentation with headers to define sections clearly and improve navigation. Use different levels of headers (e.g., #, ##, ###) to create a hierarchy and organize content logically.
  • Bold and Italics: Add emphasis to your text with bold and italics, making important information stand out.
  • Images: Integrate images into your documentation to provide visual examples, diagrams, or illustrations. This can greatly aid in explaining complex concepts, workflows, or architecture, making your documentation more comprehensive and accessible.
  • Tables: Organize information neatly in tables. This is perfect for parameter lists, version compatibility, and more.
  • Lists: Organize information in lists to improve readability and structure. Lists are great for step-by-step instructions, feature lists, or any information that benefits from a clear hierarchy or grouping.
  • Inline Code and Code Blocks: Highlight code snippets directly in your documentation. Inline code for small references and code blocks for larger examples.
  • Links: Create hyperlinks to external resources, further reading, or cross-references within your documentation.
  • Blockquotes: Use blockquotes to highlight important notes, warnings, or quotes from external sources.

With these features, you can create more structured, readable, and engaging SDK documentation, allowing users to better understand and utilize your SDK.

How to Use the New Features

Incorporating Markdown into your SDK documentation is straightforward. Here's how to get started:

  1. Open your OpenAPI specification file.
  2. Find the description fields where you want to add formatted documentation.
  3. Insert your Markdown directly into these fields.

This Markdown will be automatically converted into beautifully formatted documentation when generated through with liblab.

Example

Here's an example of how you can use Markdown in your OpenAPI specification. In this case, we are using the classic Pet Store API Spec with some Markdown added to the description:

openapi: 3.0.0
servers:
- url: https://petstore.swagger.io/v2
description: Default server
- url: https://petstore.swagger.io/sandbox
description: Sandbox server
info:
description: |
This is a sample server Petstore server.
You can find out more about Swagger at
[http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).
For this sample, you can use the api key `special-key` to test the authorization filters.


# Introduction
This API is documented in **OpenAPI format** and is based on
[Petstore sample](http://petstore.swagger.io/) provided by [swagger.io](http://swagger.io) team.

# Cross-Origin Resource Sharing
This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with
[W3C spec](https://www.w3.org/TR/cors/).
And that allows cross-domain communication from the browser.
All responses have a wildcard same-origin which makes them completely public and accessible to
everyone, including any code on any site.

# Authentication

Petstore offers two forms of authentication:
- API Key
- OAuth2
OAuth2 - an open protocol to allow secure authorization in a simple
and standard method from web, mobile and desktop applications.

version: 1.0.2
title: Swagger Petstore

This Markdown will be automatically converted into beautifully formatted documentation when generated through liblab:

The pet store docs with rich text in the description. This has headers, links, bullet points and bold text

Future Enhancements

We're not stopping here! Our team is dedicated to improving and expanding the capabilities of our SDK documentation.

Stay tuned for updates, and don't hesitate to share your feedback and suggestions. Your input is invaluable in making our tools even better. Please feel free to contact us to request features or improvements!

We hope you're as excited about this update as we are. Markdown support is a big step forward in making your SDK documentation more accessible and easier to understand.

← Back to the liblab blog

This year, we will be sponsoring the Nordic APIs Summit in Austin, TX on March 11-13. We look forward to meeting you in person and discussing our latest SDK generator.

Start generating your SDK for free today - liblab.com/join

Why stop by?

So why should you attend and stop by the liblab booth? Here are a few reasons:

Meet the liblabers

First of all, our booth will be packed with our top Engineers (friendly, too) demoing how to save developers time and effort by generating SDKs for your APIs in your own language. Coding and conversation language 🙂

A group of people posing for a selfie wearing liblab shirts standing in a carpark. 2 of the team are wearing sunglasses, and another is making a peace sign

See the 1-minute demo

Hear about our product updates and new features to help with documentation and API specs. We know it's a pain. We will demo how painful it can be and how we can reduce your pain. Worth your visit.

Visual Studio Code showing some code using a llama store SDK in Python

Snap a photo with liblab's Llama

Let's be honest: the best part of our booth is a 7-foot Llama. Snap a pic with our llama, tweet it with the hashtag #liblabLlama and tag @liblaber to get a special sticker!

A group of people wearing liblab love your SDK shirts posing with a large llama mascot also wearing the same shirt. Behind the group is the liblab booth from API world

More from liblab:

Hear us on stage, and if it's anything like the last event we attended, you'll even get to do some stretching exercises with us. We're not kidding.

Jim on a stage presenting with his arms outstretched, and the audience also stretching their arms

We will be hosting 3 sessions:

  • Build a terrible API for people you hate - 12th March, 1:10PM, API design technical track

    We've all been there - you've been asked to build an API to be used by someone you really dislike. Maybe it's the person who keep stealing your milk from the company kitchen, or the one who asks long winding questions just as the 5pm Friday meeting is about to end. It's someone who annoys you, and you have to build them an API.

    So malicious compliance time! You have to build them an API, but no-one said it has to be good. Here's your chance to get revenge on this person by building the Worst. API. Ever. This session will show you how, covering some of the nastiest ways to create an API that is terrible to use. From lack of discoverability, to inconsistent naming, this session will have it all!

    And maybe if you have to create an API for someone you love, this might give you some pointers as to what not to do...

  • From APIs to SDKs: Elevating Your Developer Experience With Automated SDK Generation - 12th March, 2:50PM, Developer experience technical track

    APIs are everywhere and are a great way for developers to access your service. But not all developers want to access APIs directly. Most want to use SDKs in their preferred programming language using the tools they already know and use everyday. These not only feel more intuitive to a developer, but bring features like type safety, documentation, and code completion.

    In this demo-heavy session, Jim will compare APIs and SDKs and show just how much a well crafted SDK can improve the developer experience. Releasing changes to your customer quickly is something every development team strives for, so Jim will go on to show you how this process can be automated, including in your CI/CD pipelines so that every API change can be released as an SDK as soon as possible with minimal engineering effort.

    By the end of this session you will have a new appreciation for SDKs and understand that creating and maintaining these does not have to be burdensome. You'll be ready to automate this process yourself and improve your own APIs developer experience.

  • 3 Quick Steps to Generate SDKs for Your APIs - 13th March, 10:10AM, Demos and lightning talks

    Learn how to generate SDKs for your APIs in 3 quick steps using liblab.

Get your ticket

Sign up now at nordicapis.com/events/austin-api-summit-2024!

← Back to the liblab blog

API's need to change over time. Features are added, bugs are fixed, and changes are made. How can you introduce and track changes without breaking client applications? API versioning is the answer. By versioning your API, you work towards building a robust and scalable product.

What is API versioning?

Versioning an API is the process that allows tracking changes and managing the API's various iterations. Essentially, versioning allows you to create multiple API versions that that coexist but operate independently of each other. That way new features can be added, updates can be made, and old features can be removed with minimal disruption of service to the user.

Why is API versioning important?

Proper versioning is a crucial step to keep projects flexible and ensure compatibility with existing and new tools. Without proper versioning, modifications to the API could cause unexpected errors and result in disruptions for the client. You’ll likely need to make changes to your API over time, so it’s a good idea to analyze whether or not implementing proper API versioning from the start would be a good idea.

A good API versioning strategy not only helps to make projects more flexible, but it can also make projects compatible with more tools and protect backwards compatibility. Over the course of the project, it can also help lower the cost of introducing new features and help communicate changes clearly to the users. Since each API version number gets its own release notes, migration guides, and updated documentation, this strategy promotes a trusting relationship with the user.

When should you version an API?

If you're going to introduce major changes to the API, it would be a good idea to consider adopting an API versioning strategy. As different versions become available, users can incrementally opt-in to new features at their own pace. Versioning can also facilitate making security updates without forcing API users into upgrades that would require downtime to incorporate.

In a situation where the API will support multiple client platforms, API versioning will allow the user to stick with their platform's SDK without being worried about updates for other platforms, and that's something we can help with — liblab offers an robust and comprehensive suite of tools to generate SDKs tailored to your API.

When should you not version an API?

Versioning isn't the best solution for every situation, though. Developing a full versioning strategy for minor updates or bug fixes will more likely add confusion than benefits. Also, in situations where there is only one or two users, such as an API that will only be used internally, it's probably more practical to just update both server and client at once. Same goes if you’re introducing a non-breaking or temporary change, or something on a branch that won't impact any clients.

How to do API versioning

If you think API versioning will be a good fit, you need to understand how to adapt API versioning to suit your needs. One of the first things you’ll want to consider is how you want to label your versioning. There’s a few options:

  1. Semantic Versioning (commonly referred to as SemVer) follows a MAJOR.MINOR.PATCH format. For more information on semantic versioning, semver.org is a good resource. It’s helpful for tracking backward-compatible changes, functionality, and bug fixes. Each of the major breaking changes are incremented as a new major version number, while backward-compatible additions and bug fixes are each just a minor version number.

  2. Date-based versioning tags make every API version number the date it was released, which might be useful in some situations where a chronological sequence of releases is more relevant than semantic clarity.

  3. Endpoint-based versioning may be helpful in limited situations where the scope of the version will only affect certain endpoints with independent resources.

There isn’t consensus on the “best” approach, it really depends on what information will help you better track the changes made to the API. Analyzing your needs and desired results will help you decide which system will work best for you.

Types of API versioning

Next, you need to decide how the user specifies which API version they want to use. Here are some options:

Versioning TypeBasicsExamplePositivesNegatives
URI VersioningThe version numbers are incorporated into a URL pathhttp://www.example.com/api/1/productsEasy to understand and implement Clearly separated API versionsCan become cluttered. Not recommended by REST architecture
Query ParameterThe version number is appended as a query parameter in the API endpointhttp://www.example.com/api/products?version=1Clear separation of API versions Easy to implementLess intuitive for API consumers. Can result in long cluttered URLs
Header BasedThe version number is a specific and unique header fieldcurl -H “Accepts-version: 1.0” <http://www.example.com/api/products>Follows REST principles Keeps URI focused on the resourcesLess intuitive. More effort is needed to check API request
Content NegotiationThe version is based on the representational state or media typecurl -H “Accept: application/vnd.xm.device+json; version=1” <http://www.example.com/api/products>Smaller footprint. No need for URI routing rules. Versions resource representations instead of entire APILess accessible for testing and exploring via browser

Again, each of these techniques have different objectives and advantages, so your specific project requirements should determine which technique is the best for you.

How to build an API versioning strategy

Once you’ve planned out what methods and techniques will best suit your constraints and objectives, you’re ready to formulate your strategy according to API versioning best practices. You’ll need to assess the project scope and define what your versioning policy will be. REST (Representational State Transfer) is a popular API architecture for building web services in which resources are accessed via standard HTTP methods. Using versioning with a REST API allows the developer to add new features to the API, fix bugs, and remove old functionality without breaking anything for the API consumers. If you’re building a REST API, there are a few principles regarding versioning that you might want to keep in mind. Here are some of those recommended api versioning strategies:

1. Communicate changes clearly

The whole point of using a REST API is so that there’s no confusion between client and server about where to access resources. That completely breaks down if you haven’t clearly communicated to the API consumers when things change on the server. You’ll need to consider release notes, migration guides, and updated API documentation to keep everyone on the same page. Perhaps it’d even be worth considering a longer time table to give users enough time to prepare for and implement updates.

2. Use Semantic Versioning

We talked about some of the other options, but semantic versioning is best in line with REST principles. Why? Because REST APIs are stateless; endpoints aren’t affected by outside constraints and function independently from one another. They (in theory, unless you really need it) shouldn’t be fixed to anything in the real world affecting their output, like the date of the most recent new version. Setting up SemVer isolates the endpoints from anything resembling state even further.

3. Maintain backwards compatibility when possible

REST APIs are uniform and consistent. In an ideal world, there would never be any breaking changes. In reality, that’s difficult to implement long-term, but always lean on the side of backwards compatibility. For example, new endpoint parameters should have default values. New features should get their own new endpoints and their own new version. Removing existing fields from API responses is also frowned upon for this reason, especially if you have a good deprecation strategy.

4. Deprecate old versions gradually

What does a good deprecation strategy look like? A clear timeline. Support old versions during the deprecation period and make sure that deprecation endpoints are recorded clearly in the API documentation. Also, be clear with the user. Make sure they’re on the same page about why older versions are being deprecated, what the benefits of upgrading to the new version are, what issues they might face, and how they make solve those issues. Ample support during the transition period will help minimize disruptions and promote trust between the developer and API consumers.

API versioning best practices

Many aspects of your API versioning strategy will be dependent on factors unique to your application, but there are some general guidelines of API versioning best practices to take into consideration.

1. Prioritize the docs

The current state of the entire API should be reflected in comprehensive documentation, customized to the latest API version. Make sure that there are clear instructions on how changes should be introduced with each new version so no user gets confused — you’d be surprised how little friction it takes to make some users jump ship.

2. Keep the line open with the clients

Good communication is key. Understand what your consumers need and how each new version will affect their workflow, not just yours. Establish good channels of communication in advance to inform users of each upcoming change and each new version. Those channels also let you gather feedback from users to understand what their needs are and what their expectations are, and that’ll help you build a roadmap for the future of your API.

3. Plan for security and scalability

While most of API versioning focuses on the functional aspect of the API, security and scalability should be taken into consideration. As new versions are introduced that protect against security threats, older versions may continue to have those since-fixed vulnerabilities. Also, if you build a good API, you’ll start eventually getting increased usage (both over time and in quick spikes) and larger data volumes. The solution? Bake in automated security checks, vulnerability assessments, and scalable practices from the start. Make security updates and patch versions a priority for every version you support, not just the latest version. That includes every major or minor patch, even the since-replaced ones. This is an even bigger area where communication is crucial, since there may even be legal obligations to inform API users of how their data security is being protected in each new update.

4. Test thoroughly

You want to catch as many issues as possible before the API gets to the user. Conduct unit tests, integration tests, and regression tests for each new version. We’ve all been through the frustration of doing an upgrade on one part of a project just to find that we accidentally broke everything else. Thorough testing at each stage of API versioning helps avoid those situations and ensures a reliable product for the user. Automated tools can greatly streamline the process.

How to test API versions

To start, you want to thoroughly test the new API version separately to ensure that it meets all the functional specifications that the new API version is supposed to meet. There’s a couple ways to do this:

1. Unit testing

Unit testing involves testing individual pieces of code. For example, does each endpoint still function like expected? Take an endpoint that just takes in a letter, and if its within a certain range of ASCII values, it’ll shift the letter by however many places you specify. Here’s a function that does that:

const shiftLetter = (letter, key, rangeStart, rangeEnd) => {
const rangeLength = rangeEnd - rangeStart;
const code = letter.charCodeAt(0);
if (rangeStart <= code && code < rangeEnd) {
let n = code - rangeStart + key;
if (n < 0) n = rangeLength - Math.abs(n) % rangeLength;
return String.fromCharCode((n % rangeLength) + rangeStart);
} else return letter;
};

These examples are from an Algolia article about unit testing. If we have standardized our API, we don’t even need to test this over HTTP requests since that part acts predictably. We can just write a little function like this to test this particular unit of code:

const testShiftLetter = () => {
if (shiftLetter("L", 3, 65, 91) != "O") throw "Assertion error"; // test basic case
if (shiftLetter("s", 14, 65, 122) throw "Assertion error"; // test wrap around, and custom ranges
};

All it does is throw an error if the function doesn’t produce the correct result. You can also measure the performance of individual units here. Each new API version requires that you rerun these tests to make sure each individual piece of the API still works as you expect, so you should build this into your automated workflow, perhaps using a tool like GitStream.

2. Integration testing

Integration testing is very similar to unit testing (some don’t even make the distinction). The difference is that now we’re testing how units of code work together to produce the right result. Here's a more complex example from that same article:

const testCaesar = () => {
if (caesar("HELLO", 1) != "IFMMP") throw "Assertion error"; // test basic case
if (caesar(caesar("DECRYPTED TEXT", 19), -19) != "DECRYPTED TEXT") throw "Assertion error"; // test negative keys for decryption
};

See how it tests expected output even in edge cases?

3. System testing

The last type of testing involves using an application built with the API, testing how everything works together. This is harder to implement, but since you’ve built such great documentation and migration guides for each new version, you likely have demos built with your API that you can test with.

How can liblab help with API versioning

One sticking point a lot of developers have with API versioning is how it interacts with the various SDKs that actually consume the API. That’s where we come in — liblab can analyze your spec and generate SDKs tailored to the needs of your API. Trying to support multiple API versions and making sure clients can abstract API complexities and maintain consistent interfacing is usually a nightmare, but how to version APIs more effectively using SDKs.. liblab’s user-friendly controls let you automatically generate flexible SDKs that include all the necessary components right out of the box.

Conclusion

It may seem daunting to consider all these factors at the beginning of a project, but the time and effort now will pay dividends through the entire lifecycle of the project. If you're in a situation where it makes sense to create an API versioning strategy, the hard work right now will definitely be worth it! Thoughtful planning and implementation of best practices will result in robust scalable APIs and ensure long-term stability and adaptability. It's important to remember that software development is an evolving landscape, so we as devs have to keep up to date with improved best practices and new methods. Doing that puts you well on your way towards creating APIs with smooth transitions between versions, enhancing the end user experience, and helping you to build strong relationships with satisfied customers.

← Back to the liblab blog

TL;DR - liblab can generate dev containers for your SDKs so you can start using them instantly. See our docs for details.

As software developers, our productivity is constantly increasing - with better tools, and even AI powered coding to allow us to deliver faster, and focus on building better solutions to more complex problems. The downside of this is the initial setup - getting our tools configured and our environments ready can be a big time sink. Anyone who has ever joined a new company with poor on-boarding documentation can attest to this! Days or even weeks trying to find the right versions of tools, and getting them configured correctly. It's almost a rite of passage for a new developer to re-write the onboarding document to add all the new tools and setup needed to get started.

This is something we see at liblab - our customers generate SDKs to increase their productivity, or the productivity of their customers, but to validate each SDK means setting up environments to run TypeScript, Java, Python. C#, Go and more. Although this is a one time cost, we decided to reduce this setup time so you can test out your generated SDKs in seconds - using dev containers!

What is a dev container?

A development container, or dev container, is a pre-configured isolated development environment that you can run locally or in the cloud, inside a container. Containers come with all the tools you need pre-installed, your code, and any configuration you need to get started, such as building or installing your code. They were designed to solve the setup problem as well as reliably deployments - set up your container once for a particular project, and everyone can share that setup. If the setup changes, the dev container changes, and everyone gets the new setup. It's also the closest thing we have to a "works on my machine" solution - if it works in the dev container, it will work for everyone. Literally like shipping your machine to your customers!

Running dev containers

Dev containers can be run locally through your favorite IDE, such as Visual Studio Code or IntelliJ, as long as you have container tooling installed such as Docker. You can also run containers in the cloud, using things like GitHub codespaces.

For example, you can create a dev container for Python development using one of your projects, that is based upon a defined version of Linux, has Python 3.11 installed, is configured to use the Python Visual Studio Code extension, and will install the required pip packages from your projects requirements.txt file when the container is created. As soon as you open this in Visual Studio Code, it will spin up the container, make sure the Python extension is installed, install your pip packages and you are instantly ready to start coding.

Dev containers isolation

Because dev containers are just that - containers, they run isolated from your local machine, so you don't need to worry about conflicting tool versions, or other conflicts. What is installed in the container just lives in the container, and what you have locally is not available inside that container. This means you can have multiple dev containers for different projects, and they won't conflict with each other. For example - you could have Python 3.11 installed locally, have one project in a dev container using Python 3.10 and another for legacy work using Python 2! Each will be isolated and have no idea about the other.

How are dev containers set up?

A dev container is defined by having a folder called .devcontainer in the root of your project. This folder contains a devcontainer.json file, which defines the container image to use, and any configuration you need to run your code. This devcontainer.json file can reference a pre-defined environment, such as Python, or NodeJS with TypeScript, or you can define your own environment using a Dockerfile.

.
└── .devcontainer/
└── devcontainer.json
└── Dockerfile

In the devcontainer.json file, you can also define any extensions you want to install in your IDE. By having the configuration in one or more files, these dev containers are instantly reproducible - check them into source code control and when someone else clones your repo and opens the folder, they will instantly get exactly the same environment.

You can read more on configuring dev containers in the dev container documentation.

How can I use dev containers with my generated SDK?

liblab can be configured to create the dev container configuration files for your SDK. This is done by an option in your configuration file:

{
...
"customizations": {
"devContainer": true
},
...
}

When you run the SDK generation process using liblab build, the generated SDK folder will come with the .devcontainer folder all ready to go. The container will be configured to not only install the relevant language tooling, but your SDK will also be installed ready to be used.

Use your dev container to test your SDK

To test your SDK in a dev container, make sure you have Docker desktop (or another Docker compliant container tool) running, and open the SDK folder for your language of choice in Visual Studio Code. You will be prompted to open the folder in a container, select Reopen in Container and your dev container will be created. This may take a few minutes the first time, but subsequent times will be much faster.

The VS Code reopen in container dialog

Let's use the dev container created with a Python SDK as an example. In this example, I'm going to use the Python SDK for our llama store API sample. Open this SDK in VS Code, or even open it in a codespace in GitHub.

Once the container is opened, a script is run to install the SDK dependencies, build the Python SDK as a wheel, then install this locally. There's no need to use a virtual environment, as the container is isolated from your local machine, so the installed wheel is only available in the container.

The output from the terminal showing the llama store SDK installed

As well as installing the SDK, the dev container will also install PyLance, the Python extension for Visual Studio Code, so VS Code will be fully configured for Python development. You can see this in the extensions panel:

The VS Code extensions panel with PyLance and the Python language server installed

This is now available from any Python code you want to run. Every SDK comes with a simple example - liblab takes the default get method and creates a small sample using this, and you can find this in the examples/sample.py file. If you open this file, you will see that VS Code knows about the SDK, with intellisense, documentation and code completion available:

The sample.py file with both code completion and documentation showing

It's now much easier to play with the SDK and build out code samples or test projects to validate your SDK before you publish it.

Conclusion

Dev containers are a great way to test out a new SDK. liblab can generate the dev container configuration for your SDK, so you can get started instantly. To find out more, check out our documentation.

← Back to the liblab blog

It's just a simple fact of life that more work (and better work) gets done when everything is well-structured and organized. That's why, for example, professional chefs keep clean kitchens, precise timings, and ordered hierarchies of responsibilities.

A chef building a plate in an organized kitchen.

It's the same reason why, if you regularly work at a desk, you probably make some effort to keep it organized (or at least you want to). Especially developers — who work in a strictly-structured world of math and logic — love straightforward direction in the form of standards.

Fortunately, the charging one has been solved now that we've all standardized on mini-USB. Or is it micro-USB?

Preview

This is why we need standardized Application Programming Interfaces (APIs): the more our API design reflects the consistency developers are expecting, the more productive they'll be with it and the more valuable it'll be to the devs and the API provider.

When we're done here, you'll be able to answer these three questions:

  • What is API standardization and what does it look like in practice?
  • How do standardized APIs actually help in general and in my industry?
  • What can help lower the API standardization barrier-to-entry?

What is API Standardization?

You know what an API is: it's just the layer of glue between two pieces of code. Technically, it applies to almost every communication between modules inside an application, as well as to every external communication to some other program. That means that every time you have two pieces of code talk to each other, they have to have agreed in advance on what kind of communication they're going to use.

For example, maybe they'll use the JSON format, and they'll send messages to each other like this:

{
result: "success",
data: {
message: "Hello from across the API!"
}
}

Now, if this API is completely inside your application, you might be fine with just sending little packets of JSON like this between pieces of code. But the moment you start dealing with more complexity, you'll realize this approach to APIs doesn't scale well. Think about all the possible edge cases:

  • Will the response JSON always contain a result key?
  • What happens if the operation wasn't a success? Where will details about the error be stored?
  • Is the body of the response always inside data? Or is it sometimes at the root level of the object?

You probably have experience building an API like this. Maybe you've directly worked through these questions with your API, or maybe not, but if you can think of definitive answers to them, then you're delving into API standardization. You're setting rules for how the pieces of code talk to each other so that it'll be completely consistent across your app.

A definition

With that example in mind, now we have enough information to write a more succinct definition:

👉 API standardization (n): the process of creating and implementing consistent rules for how two pieces of code talk to each other over an API (Application Programming Interface)

The definition of API standardization.

Those consistent rules might include coming up with answers to questions such as:

  • In what format will the data be sent, both in the request and in the response?
  • What naming convention will we use? Are we sticking with camelCase, snake_case, or something else for variable, resource, function, and endpoint names?
  • How do the standards in our industry affect our ruleset?

You're a talented dev though; you know APIs go way beyond just two files sending tiny JSON packets back and forth.

API definitions over the internet

A company (called the service provider) might let you and your program interact with their programs over the Internet. The HTTP protocol that governs this already gives us some standardization to work with, but the body of each request is almost completely unsupervised. Imagine the chaos if every time we wanted to interact with, say, the Google Maps API, we could send our requests in whatever form we wanted! It'd be almost impossible for the service provider to pick out the needed data from our request, and even if it did, it'd probably be extremely slow. Let's focus on this use case from here on out to try and figure why API standardization isn't just a nice-to-have, but a crucial element of modern, efficient Information Technology.

Importance of API Standardization

What are the benefits of having standardized APIs for external services? Here's a few reasons:

1. It gets everybody collaborating

When API consumers can trust that it's straightforward to interact with the service and build what they want without too much unnecessary hassle, they'll be motivated to go further out of their way to work with others to solve problems.

2. It keeps the bugs to a minimum

It's way easier to avoid unintended functionality when security and predictability are baked right into the messages servers and clients send to each other. This has the effect of increasing the expected uptime of the API and reducing interruptions in service provision.

3. It promotes scalable innovation on the provider's side

When the service provider already has established the input and output of a particular endpoint or function, much of the grunt work involved in adding new features goes away. Standardized APIs open up tons of future prospects moving forward because the developers building the API can afford to be more creative.

4. It simplifies documentation and improves developer experience

Developers already keep track of enough, so if the learning curve is too high to interact with an API, they'll just avoid it. API standardization simplifies docs because we can remove all of the things that the rules make too obvious or too redundant to explain again. Standardization means developers can more easily find what they're looking for in the docs, flattening the learning curve and making the API more approachable to a wider range of users.

5. It reduces long-term technical debt in actual implementations

If the communication both between modules and to outer systems is standardized with an API and consistent rules, it removes the complexity that would otherwise need to be managed in the future, which helps to reduce operational costs that would come with it.

API Standardization Use Cases

Healthcare

Standardized Application Programming Interfaces are incredibly important in healthcare because data scattered among many systems affects how doctors and pharmacists work. For example, imagine you moved from South Carolina to Louisiana, so your providers, insurance company, pharmacies, and other healthcare connections all changed. What if, because the providers in South Carolina didn't have an easy, standardized API to upload your current prescriptions to a centralized database, your new healthcare providers in Louisiana prescribed you a conflicting medicine and damaged your health?

Smart API design prevents potentially life-threatening gaps in data sharing, and that's one of the biggest reasons why API standardization has gained industry-wide adoption in healthcare.

Government

Public services are notoriously difficult to use. Just the word “bureaucracy” comes with negative connotations because workers in different departments have the reputation of (to put it kindly) preferring to keep necessary information to themselves. In contrast, APIs are designed to bring people together through data and promote efficient information technology. No wonder standardized APIs have been a digital transformation in the government sector.

For the United States government, there's an official standard that requires several main objectives to be fulfilled:

  1. Make it available to everyone by putting new APIs in the directory.
  2. Use the API outer layer common to all government APIs for analytics, authentication, and security.
  3. Get versioning right. Wondering how? See our recent article on what makes API versioning so necessary and how to do it.
  4. Build public docs. Thankfully, this is way easier because we're working with standardized APIs.
  5. Have a feedback mechanism where users can report issues and ask questions. Feedback builds trust and also helps retain API users who are having trouble and are ready to quit.
  6. Use OpenAPI spec files to make it clear to users how to access the APIs, and make sure these OpenAPI specs don't suck!
  7. Use the normal endpoint design. Creativity is usually a positive, but once it starts causing mass confusion, it's not worth it.

You're not bound to these rules, but it might be worth implementing them at your company because they're a great way to make sure the principles of API standardization come through in the actual implementations you build.

Financial Services

Financial service technology (a.k.a. “fintech”) companies love APIs and standardization. There's a couple particularly strong reasons:

First, the modern shift toward open banking means customers are just expecting financial institutions to easily talk to each other. For example, in some countries you can set up investment accounts to pull directly from your bank. As a modern user would expect, there was no copy-and-pasting routing numbers, no hacky tiny deposits, no three-day wait, because they have standardized APIs (probably served via Plaid) for connecting the two accounts.

Plaid in action

Also, many smaller companies don't have the infrastructure to run payment data themselves. A typical small business would find it way easier to use something like Stripe, a company that created API definitions for payment methods, invoices, charges, refunds, and every other piece of the payment process. That means that by using their API, we can get from hypothetical ideas to actual implementations really quickly.

Third, like we mentioned earlier, standardized APIs have plenty of security benefits too. That's especially great for fintech companies because they deal with extreme amounts of regulation to prevent data leaks and keep their customers' money and business data safe.

And as always, they're businesses that want to distinguish themselves from the competition. By adopting the principles of standardized APIs, they can focus on innovation and coming up with new ideas that'll grow the business.

How liblab Can Help With API Standardization

One of the biggest benefits of creating standard API definitions for endpoints and resources is that it allows you to automate building Software Development Kits (SDKs) out of your API.

That's where liblab comes in. Before, a small change in how your API worked meant you had to update every piece of code that used the API. But by putting liblab into your workflow, you can automatically generate the language-specific libraries through which your customers and clients will use your tool straight from the API design file, written to the OpenAPI spec. This means that you won't be bothered by the language-specific bugs and intricacies that would normally drag down a project that others depend on — instead, you'll get to efficiently spend time on what strengthens future prospects moving forward, like new API features and performance optimizations.

A pitch for standardized Application Programming Interfaces

Want a quick pitch to bring to the folks in charge of your APIs? Here's a summary of what we've learned so far:

  • APIs need consistency to be useful.
  • API standardization helps facilitate developer collaboration, simplify maintenance, promote faster innovation, make the developer experience more enjoyable, and limit technical debt.
  • Many industries needed API standardization, and how they implemented it can help you decide how to implement it at your company to improve your future prospects.
  • liblab's experts can help you through it. Benefit from our expertise by signing up for liblab.

Now that you're an expert in API standardization, set yourself up for long-term success by partnering up with liblab and automating SDK generation based on your standardized Application Programming Interfaces.

← Back to the liblab blog

At liblab we generate software development kits, or SDKs, for your APIs. But what do we mean by 'SDK generation', and how does it work? This post explains everything you need to know about SDK generation, and how it can help you make your APIs more accessible.

What is SDK Generation?

Put simply, SDK generation is the process of automatically generating SDKs from an API specification. You have an API exposed using something like REST, and you want to make it easier for developers to access that REST API.

You could just let them access the API directly, but this relies on your user not only being experts in their own domains, but also knowing how to make REST calls, and to a certain degree the best practices for using your API. By creating an SDK, you are building a layer of abstraction over that API, embedding those best practices into the internals of the SDK code, and providing a nicer interface to your API in the programming languages that the developer is using.

In my experience, every team of developers that accesses APIs will always build some kind of layer of abstraction themselves. This will contain things like wrapper objects for the requests and responses to avoid using JSON, and service classes that wrap the REST requests in methods. These layers of abstraction may also include things like authentication, refreshing access tokens, retries, and error handling. This takes a lot of work, and is often not shared between teams in an enterprise who are all using the same API.

By auto generating an SDK, you can provide this layer of abstraction for your API, and ensure that all developers are using the same best practices. This cuts down on the boilerplate code being written, and allows developers to focus on solving real problems instead of wrapping JSON and REST. You don't write swathes of code, you use a tool that will do all the hard work for you, taking in your API and spitting out an SDK.

A machine that coverts APIs to SDKs

This auto generation also handles updates - add a new endpoint to your API? Regenerate the SDK, and the new endpoint will be available to your users. This means that your users will always have access to the latest version of your API, and you don't need to worry about them using an old version of your SDK.

Read more on a comparison between APIs and SDKs.

How Does SDK Generation Work?​

SDK generation is computers writing code for you. A tool takes an API specification, and generates code that can be used to access that API. The SDK code is generated in the programming languages of your choice.

REST API Validation​

Every generated SDK starts from an API specification. These use standards like OpenAPI to define the API - including the endpoints that can be called, and the expected data that will be sent as the request body, or the response of the call.

For example, your spec might have an endpoint called llama/{llama_id} that takes a llama Id in the URL, and returns a JSON object containing the details of that llama. The spec will define the URL, the HTTP method (GET), and the expected response body.

/llama/{llama_id}:
get:
tags:
- llama
summary: Get Llama
description: Get a llama by ID.
operationId: get_llama_by_id
parameters:
- name: llama_id
in: path
required: true
schema:
type: integer
description: The llama's ID
title: Llama Id
description: The llama's ID
responses:
'200':
description: Llamas
content:
application/json:
schema:
$ref: '#/components/schemas/Llama'
type: array
items:
$ref: '#/components/schemas/Llama'
title: Response 200 Get Llama By Id

The endpoints use schemas to define the objects that are sent or returned. In the example above, the response is defined as an array of Llama objects. The schema for a Llama object might look like this:

    Llama:
properties:
name:
type: string
maxLength: 100
title: Name
description: The name of the llama. This must be unique across all llamas.
age:
type: integer
title: Age
description: The age of the llama in years.
color:
allOf:
- $ref: '#/components/schemas/LlamaColor'
description: The color of the llama.
rating:
type: integer
title: Rating
description: The rating of the llama from 1 to 5.
id:
type: integer
title: Id
description: The ID of the llama.
type: object
required:
- name
- age
- color
- rating
- id
title: Llama
description: A llama, with details of its name, age, color, and rating from
1 to 5.

Before the SDK can be generated, the API needs to be validated. For example - the llama/{llama_id} endpoint returns a llama object defined using the #/components/schemas/Llama schema. If this doesn't exist, then the SDK cannot be successfully generated. The validation will also look for other things - for example, does the endpoint have operationId defined for each verb, which is used to generate the method name in the SDK. Are there descriptions for each endpoint, which can be used to generate the documentation for the SDK.

liblab can validate your API spec, and will give you a list of issues to resolve before you generate your SDK. The better your spec, the better your SDK will be.

SDK Generation

Once your API has been validated, the SDK can be generated. This is done by taking the validated API specification, and adding a sprinkle of liblab magic to generate the SDK code. This 'magic' is smart logic to build out model objects that match the requests and responses, as well as generating services that wrap the REST calls. The models handle missing fields in the responses, or patterns that are defined (such as ratings needing to be between 1 ans 5, or an email address field needing to be a valid email). The services implement required logic such as retrying failed requests, handling authentication, refreshing access tokens, and handling errors.

SDK generation also understands the programming language that you want to generate the SDK in. This means that the generated code will be idiomatic for that language. For example naming will be idiomatic to the language, so for the above llama example, the service will be called Llama in Python and C#, but the method to get a llama by Id will be get_llama_by_id in Python, and GetLlamaByIdAsync in C# - using snake case for Python and Pascal case for C#. The generated code will also use the idiomatic way of handling asynchronous calls - for example, in C# the generated code will use Task and async/await to handle asynchronous calls, naming them with the Async suffix.

A lot of the features generated in the SDK can be customized. For example, you can customize how retries are handled, including how many attempts and the time between retries. You can even hook into the API lifecycle and add custom logic to handle requests before they are sent, or responses before they are returned to the caller.

Documentation Generation​

As well as generating SDKs, liblab also generates documentation for the SDK from the validated API. This documentation not only shows how to call the API directly using tools like curl, but also code samples showing how to use the SDK. This way developers can literally copy and paste code examples from your documentation to get started quickly using your SDK.

This documentation is built using the descriptions and examples from the API spec, so the better the documentation in the spec, the better the documentation for the SDK. Your code samples will include these examples.

Packaging​

Its all very well to create an SDK, but you need to be able to store the code of your SDK somewhere, and distribute it to your users, and this is typically via a package manager like PyPi, NPM or NuGet. liblab generates all the relevant package manifest files, and can raise a pull request against your repository to add the generated SDK code. You can then review the PR, merge it, and publish the package to your package manager of choice, either a public package manager, or an internal one.

Best Practices For SDK Generation

Here are some best practices for SDK generation, to help you get the most out of your generated SDKs.

Understand Your Users’ Needs

The most important part of any software development process is:

Know thy user

Understand what your user needs. This might be their requirements for your SDK, or it will be your knowledge of how the SDK should work to give your users a seamless experience.

Generate for the users preferred programming languages

What programming languages are your users likely to use? For example, if you are developing for a large enterprise, chances are a C# and Java SDK might have a larger audience than a Go SDK. Smaller companies might be more likely to use Python or TypeScript.

Build for your users - and the big advantage of using SDK generation tools like liblab is growing the languages you support can be as simple as adding a new language to your config file, then packaging up the SDK for distribution to your users.

Simplify the Authentication Process

Authentication is hard, and everyone hates writing code to authenticate against an API. Make it easy for your users by handling authentication in the SDK. This might be as simple as providing a method to set the access token, or it might be more complex, such as handling the OAuth flow for your users by hooking into the API lifecycle.

SDKs can also handle refresh tokens, so if you want a persistent connection to your API, you can handle refreshing the access token in the SDK, and your users don't need to worry about it. This is very useful when writing server code that will run for months or even years on end, rather than desktop apps where the user will log in each day.

Have a good API spec

The old adage of 'garbage in, garbage out' applies here. If your API spec is not well defined, then the generated SDK will not be well defined.

Make sure you have tags and operation Ids defined, so the SDK services can be well named and grouped correctly - SDK generation uses the tag property to group endpoints into services, and the operationId to name the methods in the service (adjusting for different programming languages of course). For example, with this spec:

/llama:
get:
tags:
- llama
operationId: get_llamas
/llama_picture:
get:
tags:
- llama_picture
operationId: get_llama_pictures

This will give:

Service nameMethod name (Python)Method Name (C#)
llamaget_llamasGetLlamasAsync
llama_pictureget_llama_picturesGetLlamaPicturesAsync

Without these, the endpoints will be grouped into one service, and the names will be generated from the method and the URL, which might not give what you want.

For help on improving your OpenAPI spec, check out our Why Your OpenAPI Spec Sucks blog post.

Have Examples and descriptions

When coding, examples always help, giving developers something to start from when using a new SDK or library (the old joke about most code bring copied and pasted from Stack Overflow). The same applies to SDKs - if you have examples in your API spec, then these will be used to generate examples in the SDK documentation, and your users can copy and paste these examples to get started quickly.

Examples also help your users understand what data they should send to your API, and what they will get back. This is especially important for complex objects.

Descriptions are converted into code documentation, both in the SDK and in the docs that accompany it. These make it easier for your users to understand what the SDK is doing, and how to use it. In the example below, the documentation comes from the description in the API spec. The spec is:

APITokenRequest:
properties:
email:
type: string
title: Email
description: The email address of the user. This must be unique across all users.
password:
type: string
title: Password
description: The password of the user. This must be at least 8 characters long, and contain
at least one letter, one number, and one special character.

This gives the following documentation in your Python SDK:

A documentation popup for an APITokenRequest showing the descriptions of the email and password properties

Conclusion

SDKs make APIs more accessible for your users, and automatically generating SDKs makes it easier for you to provide SDKs for your APIs. liblab can help you generate SDKs for your APIs, and we can help you with the process of generating SDKs, and the best practices for doing so. Get in touch to find out more.

← Back to the liblab blog

Move fast! Break things! As developers on an agile team, we repeat these words constantly, always at least right up until the moment when something actually breaks. Then it turns out, despite all our oft touted slogans, what everyone really meant was: move fast without breaking things. Duh, why didn't we think of that sooner?

I want to talk about API-First Development because I believe an API-First approach will lead to a faster and more scalable approach to developing software applications—without breaking as many things along the way.

What does “API-First Development” mean?

API-First Development prioritizes the design and development of the API as the foundation for your entire architecture. This means taking extra care to treat your API as a product in its own right (even if it's only going to be consumed internally by your own developers). This might require a bit more planning and collaboration between stakeholders, but there are a lot of good reasons to invest a little bit of extra time up front.

Why API-First Development?

More traditionally, tech companies often started with a particular user experience in mind when setting out to develop a product. The API was then developed in a more or less reactive way in order to transfer all the necessary data required to power that experience. While this approach gets you out the door fast, it isn't very long before you probably need to go back inside and rethink things. Without an API-First approach you feel like you're moving really fast, but it's very possible that you're just running from the front door to your driveway and back again without ever even starting the car.

API-First Development flips this paradigm on its head by treating the API as the foundation for the entire software system. Let's face it, you are probably going to want to power more than one developer, maybe even several different teams, all possibly even working on multiple applications, and maybe there will even be an unknown number of third party developers. Under these fast paced and highly distributed conditions, your API cannot be an afterthought.

As a software system matures, its real value emerges from its integration into a more complex whole. Features and products are like big delicious juicy fruit hanging off a branch. Your API is the entire freakin' tree!

How do I get Started?

So you're feeling ready to dive into API-First Development? Spectacular! Trust me, the little bit of extra work up front will pay off big time down the road, and you'll start seeing the impact almost immediately.

The first step is to design and document your API. Don't worry, this isn't as complicated as it might sound. Just create an API Spec File. This file will serve as both blueprint and documentation for your API. There are several varieties in common use today (OpenAPI, Swagger to name 2). We don't need to stress out about which one to choose right now. The important thing is that all of these specifications provide standardized and machine-readable representations of your API. This standardization pays dividends later by helping you collaborate better, work more efficiently, beef up security, and seamlessly integrate with external systems.

Here's the best part: writing these specs is not as hard as you may first think. If you can handle writing the actual server code for your API, then you will pick up any of these specifications in no time at all. It's a natural extension of what you're already doing.

This may all seem a bit time-consuming at first, but trust me, that small investment up front will save you heaps of time down the road, especially once you start leveraging the power of code generators like liblab. These tools can do all sorts of cool stuff like generating SDKs and documentation for your API. Imagine making a change in one place, and boom! It's instantly updated across all the SDKs used by internal and third-party developers, as well as in your documentation.

Wouldn't that save you time? That's the transformative power of API-First development.

Conclusion

An API-First approach might not be the perfect fit for every use case. If you're working on a small app or a prototype with limited integration needs, going all out with extensive documentation and code generation might not be your cup of tea. Likewise, if you're dealing with a legacy application with its own well-established API, convincing management to dedicate the time and resources to document that API thoroughly might not be feasible. In most other cases however, adopting a more proactive API-First approach to development can unlock some serious benefits.

In today's interconnected digital landscape, it's high time that we start treating APIs as first-class citizens in our architectures. A top-notch API design sets the stage for innovation by enabling developers to leverage existing functionality in new and unexpected ways. On top of this, APIs fuel collaboration by boosting interoperability between systems. Given all these undeniable advantages, the only thing holding most developers back is a lack of knowledge. So buckle up then, and let's write a spec! Oh, and make sure it doesn't suck - learn some tips in this blog post from Sharon Pikovski.

← Back to the liblab blog

If you build APIs, you need to document them. After all, for your users to use your API, they need to know how to use it. A common phrase I like to use as someone who writes a lot of docs is "if it's not documented, it does not exist" - your users can only use a feature if they can discover not only that it exists, but how to use it.

So what is API documentation? How should you write it? What should you include? What are the best practices? In this post I'll answer all of these questions and more and give you some best practices for creating API documentation.

What is API Documentation?

API documentation is the collection of materials your users can use to learn how to effectively build apps using your API. It should contain a range of things:

  • API Reference documentation for the endpoints, parameters, request and response objects, and expected status codes
  • Examples of using the API
  • Examples for the request and response objects to help users know what to pass and what to expect back
  • Error messages and status codes that can be returned, and what they mean
  • Basic usage guides such as how to get started, authentication, and common scenarios
  • Tutorials for more complex scenarios

Why is API Documentation Important?

API documentation is how your users know how to use your API. Without it, they will at best struggle to use your API, and at worst have no idea how to do anything. APIs are lacking in discoverability - without any kind of documentation you literally cannot know what endpoints to call. Even with a list of endpoints, you still need to know what to pass to them, and what to expect back.

For even better discoverability, you can use liblab to generate SDKs from your API specs. SDKs are a much better developer experience than using APIs directly, allowing you to discover the functionality and request and response objects through tools such as IDE autocompletion.

Documentation goes beyond discovering what your API does, it also explains details on how to use it effectively. This can include how to correctly authenticate, how to handle errors, and best practices for using the API.

For example, if you call an endpoint to retrieve some data and you get a 404 status code returned. Does that mean the data does not exist, or that you don't have permission to access it? Good documentation will explain this, and give you the information you need to handle it correctly.

How and where to write API Documentation?

The best place to write API documentation is in your API!

API Specs

When you publish your API, you should always also publish an API spec. This is generated documentation that lists your API endpoints and the request and response objects, and uses standards like Swagger or OpenAPI. The big advantage of this is a lot of the time this can be autogenerated! For example if you are using FastAPI (a Python framework for building APIs) to generate your API, you can have the framework create an OpenAPI spec with no extra code to write.

API specs as a default provide a list of endpoints, what is expected for endpoint parameters, and the request and response objects. These are JSON or YAML documents, so out the box not that easy to read - but there are plenty of tools that can convert these into nice hosted documentation (FastAPI for example has this built in), and again can be built into your API tools or hosting process.

For example, we have a llama store as a reference API for building SDKs against, and it has a spec that is 1115 lines of JSON (you can read it on our GitHub if you want some light bedtime reading). This is small compared to some specs we see at liblab, with over 40,000 lines not uncommon! Reading this much JSON is hard, so there are plenty of tools that render this direct from the API. For example, FastAPI as mentioned before generates OpenAPI specs, as well as hosting generated documentation:

The hosted docs for the llama store

You can see these docs yourself, just clone the llama store, run it locally and access localhost:8000/docs.

Adding documentation to API Specs

As well as these specs listing your endpoints, they can also include a wide range of documentation. This includes:

  • Top level API documentation where you can describe in detail the API, such as how to use it, how to authenticate, and best practices
  • Endpoints descriptions
  • Descriptions and examples for endpoint parameters
  • Description and examples for request and response objects
  • Descriptions for different status codes, including why they might be returned, and what data might some with them

For example, the llama store has a top level description in the OpenAPI spec:

{
"openapi": "3.1.0",
"info": {
"title": "Llama Store API",
"description": "The llama store API! Get details on all your favorite llamas.\n\n## To use this API\n\n- You will need to register a user, once done you can request an API token.\n- You can then use your API token to get details about the llamas.\n\n## User registration\n\nTo register a user, send a POST request to `/user` with the following body:\n \n```json\n{\n \"email\": \"<your email>\",\n \"password\": \"<your password>\"\n}\n```\nThis API has a maximum of 1000 current users. Once this is exceeded, older users will be deleted. If your user is deleted, you will need to register again.\n## Get an API token\n\nTo get an API token, send a POST request to `/token` with the following body:\n \n```json\n{\n \"email\": \"<your email>\",\n \"password\": \"<your password>\"\n}\n```\n\nThis will return a token that you can use to authenticate with the API:\n\n```json\n{\n \"access_token\": \"<your new token>\",\n \"token_type\": \"bearer\"\n}\n```\n\n## Use the API token\n\nTo use the API token, add it to the `Authorization` header of your request:\n\n```\nAuthorization: Bearer <your token>\n```\n\n\n",
}
}

This is actually set in code - something that FastAPI supports is adding these kinds of OpenAPI values to your API code:

app = FastAPI(
servers=[{"url": "http://localhost:8000", "description": "Prod"}],
contact={"name": "liblab", "url": "https://liblab.com"},
description="The llama store API! Get details on all your favorite llamas.\n\n## To use this API\n\n- You will need to register a user, once done you can request an API token.\n- You can then use your API token to get details about the llamas.\n\n## User registration\n\nTo register a user, send a POST request to `/user` with the following body:\n \n```json\n{\n \"email\": \"<your email>\",\n \"password\": \"<your password>\"\n}\n```\nThis API has a maximum of 1000 current users. Once this is exceeded, older users will be deleted. If your user is deleted, you will need to register again.\n## Get an API token\n\nTo get an API token, send a POST request to `/token` with the following body:\n \n```json\n{\n \"email\": \"<your email>\",\n \"password\": \"<your password>\"\n}\n```\n\nThis will return a token that you can use to authenticate with the API:\n\n```json\n{\n \"access_token\": \"<your new token>\",\n \"token_type\": \"bearer\"\n}\n```\n\n## Use the API token\n\nTo use the API token, add it to the `Authorization` header of your request:\n\n```\nAuthorization: Bearer <your token>\n```\n\n\n",
openapi_tags=tags_metadata,
version="0.0.1",
redirect_slashes=True,
title="Llama Store API",
)

This then gives these docs:

The rendered top level description

You may notice that the description has markdown! This is nicely rendered in the docs. This is a great way to add rich documentation to your API specs, and is a great way to add tutorials and best practices. This rich documentation can also provide code examples, error messages and more.

This generated documentation should not just be made available via your API, but also hosted on a public documentation site.

Additional documentation

As well as documenting your API in the API spec, you can also add additional documentation on your public documentation site. Your API docs become the reference documentation, but you should add tutorials, how to guides, and best practice documentation as well.

Your API spec documentation can define what each endpoint does and how to call it, but it may not define the correct flow that a user might take for a typical task. For example, if your API has long running tasks, you may need to document how a user can trigger a task, check the status, then retrieve the result, all using different endpoints.

Who Should Write API Documentation?

As someone who started out in engineering before I moved to developer relations, I know how hard it is to write documentation. It's not something that comes naturally to most engineers, and it's not something that most engineers enjoy doing. But it is something that is important, and something that needs to be done.

In a perfect world, your documentation would be written by a dedicated technical writer, working in collaboration with the engineers to understand how the API works, and with the product teams to understand the end-to-end user experience. They should then feed this documentation back to the engineers to add to the API spec.

We all don't live in a perfect world though, so the next best thing is to have the engineers and product teams write the documentation. They know the API best, and can write the most accurate documentation.

Ideally you should use a framework for your API that makes writing these docs easy - for example FastAPI as mentioned before makes it easy to add documentation to your API code, and then generates the OpenAPI spec for you. This way you can even 'enforce' this by having a check for documentation in your pull request review process, or in a linting check in your CI/CD pipeline.

As an API provider - make sure you have documentation firmly in your process!

API Documentation Best Practices

Here are some API documentation best practices for writing api docs:

1 - Write in clear language

A good rule for everyone writing any documentation, including creating API documentation, is to be as clear as possible. Avoid jargon, unless it is necessary technical terminology for your product, and find ways to define this, or link to other documentation. There are some things you can assume your users know, but don't assume they know everything. It's helpful to define a minimally qualified reader, which defines the minimum knowledge or skills for each piece of documentation, and write for them.

For example, you can assume that your users know how to call an API (though a link to a guide on this is always helpful), but you can't assume they know how to authenticate, or what a JSON object is. As you document more advanced functionality, you can assume some knowledge of your API, such as assuming they know how to create a new user when documenting how to interact with that user.

2 - Show, don't tell

For any documentation, showing is better than telling. Examples always help - it's amazing how much easier it is to understand something when you can see it in action.

This is true for API documentation as well. If you want to teach someone how to get data from your API, show them the request, and what response they will get. When using your API, users could be using one of many programming languages, so provide code examples for the main ones. For example, if your API is targeted towards an enterprise, have code examples in C# and Java.

3 - Add references docs, tutorials, and guides

Documentation comes in a variety of modes, and it is good to implement them all. These are:

  • Tutorials - learning oriented
  • How to guides - task oriented
  • Explanation - understanding oriented
  • Reference docs - information oriented

I won't go into these in more depth here, but read up on Diátaxis for more information.

Reference docs and explanation should be in your API specs, and hosted on your public documentation site. Tutorials and how to guides can be on your public documentation site.

Your tutorials should also always have a quickstart. Humans like instant gratification, so being able to very quickly get started with an API is a great motivator to learn more and use it more. If a user struggles to even do the basics, they are likely to drop your API and move to a competitor. That initial documentation is crucial to keeping users engaged.

4 - Add code samples

Code samples always help! You users are engineers after all, and will be accessing your API using code. Code samples allow them to quickly craft API calls, and see what they will get back. They also allow you to show best practices, such as how to handle errors, and how to handle pagination.

Obviously the best code samples are using an SDK instead of an API - something liblab can help with!

5 - Keep it up to date

This is sometimes the hardest. When an API has no documentation there's often a big effort around writing api documentation once, usually before a big release, but no continuous time given to keeping the api docs up to date - changing them as features change or adding new features.

This is why it's important to have documentation as a part of your engineering and release process. Don't let any feature out the gate without docs, add documentation to your PR processes, or add checking for docs to your CI/CD pipelines. If you have a dedicated technical writer, they can help with this, but if not, make sure the engineers and product teams are writing the docs as they write the code.

Feature flags can be particularly helpful here, allowing features to be released, but not turned on until the docs are ready (and maybe turned on for the doc writers so they can verify what they are writing).

6 - Make it accessible

Accessibility is important for documentation as well as your API. Make sure your documentation is accessible to everyone, including those with visual impairments. This means when you render it on a docs site using good color contrast, and making sure any images have alt text. It also means making sure your documentation is accessible to screen readers, and that any code samples are accessible.

You also may have users who don't speak the default language of your company, so consider translating your documentation into other languages. This is a big effort, but can be done in stages, starting with machine translations for the most popular languages for your users, and moving on to human efforts.

7 - Make it someones problem

The best way to ensure you have good docs, is to have someone responsible. This is the person who can hold up a release or turning on a feature flag if docs are not ready. Without someone taking responsibility, it's easy for docs to be forgotten about, and for them to become out of date. "Oh, we'll do it later, we need to release for customer X" is the start of the slippery slope to no useful docs.

Make your SDKs better with good API documentation

The other big upside of good API documentation is it can automatically become the documentation for your SDK. With liblab, every time you generate an SDK, the documentation and examples are lifted from your API spec and included in the SDK. For example, with the following component in your API spec:

APITokenRequest:
properties:
email:
type: string
title: Email
description: The email address of the user. This must be unique across all users.
password:
type: string
title: Password
description: The password of the user. This must be at least 8 characters long, and contain
at least one letter, one number, and one special character.

You would get the following documentation in your Python SDK:

A documentation popup for an APITokenRequest showing the descriptions of the email and password properties

Conclusion

Your users deserve good documentation for your API, and for any SDKs generated from them. With liblab, you can generate high quality SDKs from your API specs, and include the documentation and examples from your API spec in the SDKs. This means you can focus on writing good API specs and writing good API documentation, and let liblab do the hard work of generating the SDKs and documentation for you.

← Back to the liblab blog

This is a guest post by Emmanuel Sibanda, a Full Stack Engineer with expertise in React/NextJS, Django, Flask who has been using liblab for one of his hobby projects.

Boxing data is very hard to come by, there is no single source of truth. One could argue that BoxRec is the 'single source of truth'. However, you will only find stats on a boxer's record and a breakdown of the fights they have had on BoxRec. If you want more nuanced data to better understand each boxer you would need to go to CompuBox to get data on punch stats recorder per fights. This doesn't include all fights, as they presumably only include fights that are high profile enough for CompuBox to show up and manually record the number and type of punches thrown.

Some time back I built a project automating retrieving data from BoxRec and enriching this with data from CompuBox. With this combination of data, I can analyze;

  • a boxer's record (eg. what is the calibre of the opponents they have faced, based on their opposition's track record)
  • a boxer's defense (eg. how many punches do their opponents attempt to throw at them in each recorded fight and on average, how many of these punches actually land). I could theoretically breakdown how well the boxer defends jabs, power shots
  • a boxer's accuracy using similar logic to above
  • how age has affected both a boxer's accuracy and defense based on the above two points
  • a comparison of whether being more defensive or accurate has a correlation to winning a fight (eg. when a fight goes the full length, do judges often have a bias towards; accuracy, aggression or defense)

These are all useful questions, if you want to leverage machine learning to predict the outcome of a fight, build a realistic boxing game or whatever reason, these are all questions that could help you construct additional parameters to use in your prediction model.

Task: Create an easily accessible API to access the data I have collected

Caveat: I retrieved this data around November 2019 - a lot has happened since then, I intend to fetch new data on the 19th of November 2023.

When I initially built this project out, initially a simple frontend enabling people to predict the outcome of a boxing match based on a machine learning model I built using this data, I got quite a few emails from people asking me how I got the data to build this model out.

To make this data easily accessible, I developed a FastAPI app, with an exposed endpoint for data retrieval. The implementation adheres to OpenAPI standards. I integrated Swagger UI to enable accessibility directly from the API documentation. You send the name of a boxer and receive stats pertaining their record.

Creating an SDK to enable seamless integration using liblab

I intend to continue iteratively adding more data and ensuring it is up to date. In order to make this more easily accessible I decided to create a Software Development Kit. In simple terms, think of this as a wrapper around the API, that comes with pre-defined methods that you can use, reducing how much code you would need to write to interact with the API.

In creating these SDKs, I ran into a tool; liblab, an SDK as a service platform that enables you to instantly generate SDK in multiple languages. The documentation was very detailed and easy to understand. The process of creating the SDK was even simpler. I especially like that when I ran the command to build my SDKs I got warnings with links to OpenAPI documentation to ensure that my API correctly conformed to OpenAPI standards, as this could result in creating a subpar SDK.

Here's a link to version 1 of the BoxingData API.

Feel free to reach out regarding any questions you have, data you want me to include and if you want me to send you the SDKs (Python and TypeScript for now). You can find me on LinkedIn and Twitter.

← Back to the liblab blog

SDK and API are 2 terms banded around a lot when developers think about accessing services or other functionality. But what are they, and what are the differences between them? This post will teach you everything you need to know and how SDKs can benefit your software development process!

Key Differences: SDK vs API

API (Application Programming Interface) is a set of rules that allow different software applications or services to communicate with each other. It defines how they can exchange data and perform functions. APIs are often used for integrating third-party services or accessing data from a platform, and they are language-agnostic.

SDK (Software Development Kit) is a package of tools, code libraries, and resources designed to simplify software development for a specific platform, framework, or device. SDKs are platform-specific and provide pre-built functions to help developers build applications tailored to that platform. They are typically language-specific and make it easier to access and use the underlying APIs of the platform they are designed for.

As we compare SDK vs API, here are some key differences:

APISDK
Pass data as JSONPass data as strongly typed objects
Call endpoints defined using stringsCall methods or function
No compiler or linter checkingCompiler and linter checking
No automatic retriesAutomatic retries can be defined in the SDK
You have to read the docs to discover services or learn what data to pass or receiveIntellisense and documentation
Can be called from any programming language, as well as tools like Postman or low/no-code toolsCan only be called from compatible languages

What is an Application Programming Interface (API)?

An API, or application programming interface is an interface to a system that application programmers can write code against. This reads like I'm just juggling the words around, so let's break down this statement.

There are many systems and services out there that you might want to integrate into your application. For example, you might want to use Stripe as a payment provider. As you program your application, you need to talk to these services, and these services define an interface you can use to talk to them - this interface lists all the things you can do with the service, and how to do them, such as what data you need to send or what you will get back from each call.

Application Programming Interfaces in the modern world

In the modern software development world we think of APIs as a way of making calls to a service over networks or the internet using standard protocols. Many services have a REST API - a set of web addresses, or URLs, you can call to do things. For example, a payment provider API will have endpoints you can call to create a payment or authorize a credit card. These endpoints will be called using HTTP - the same technology you use when browsing the internet, and can take or return data either in the URL, or attached to the call in what is called the body. These are called using verbs - well defined named actions, such as GET to get data, or POST to create data.

An API with 2 methods exposed, a GET and a POST on the /user endpoint An API with 2 methods exposed, a GET and a POST on the /user endpoint

Calling APIs

Calling an API endpoint is referred to as making a request. The data that is returned is referred to as a response.

APIs can be called from any programming language, or from tools like Postman.

There are many protocols APIs can use, including REST, gRPC, GraphQL and SOAP. REST is the most common, and the one I'll be referencing in this article.

What is a Software Development Kit (SDK)?

A software development kit is a code library that implements some kind of functionality that you might want to use in your application.

What can SDKs be used for?

SDKs can implement a huge range of functionality via different software components - they can include visual components for desktop or mobile apps, they can interact with sensors for embedded apps, or provide frameworks to speed up application development.

SDKs for your APIs

Another use case for SDKs is to provide a wrapper around an API to make it easier to call from your application. These SDKs make APIs easier to use by converting the calls you would make into methods, and wrap the data you send and receive in objects.

An SDK with 2 methods exposed, a getUser method that wraps the GET on /user and a createUser that wraps the POST on /user An SDK with 2 methods exposed, a getUser method that wraps the GET on /user and a createUser that wraps the POST on /user

These SDKs can also manage things like authentication or retries for you. For example, if the call fails because the service is busy, the SDK can automatically retry after a defined delay.

For the rest of this article, when I refer to SDKs I'll be talking about SDKs that wrap APIs.

How Do APIs Work?

APIs work by exposing a set of endpoints that you can call to do things.

API Endpoints

These endpoints are called using verbs that roughly align to CRUD (create, read, update, delete) operations.

For example, you might have a user endpoint that handles the following verbs:

VerbDescription
GETRead a user
POSTCreate a user
PUTUpdate a user
DELETEDelete a user

API Data

Data is typically sent and returned as JSON - JavaScript object notation. For example, a user might be returned as:

{
"id": 42,
"firstname": "Jim",
"lastname": "Bennett",
"email": "jimbobbеnnе[email protected]"
}

How Do SDKs Work?

Software Development Kits work by wrapping the API calls in code that is easier for developers to use.

Creating a user with an API

For example, if I wanted to create a user using an API, then my code would need to do the following:

  1. Create an HTTP client - this would be code from a library that can make HTTP calls.
  2. Create a JSON object to represent my user.
  3. If my API requires authentication, I would need to get an access token and add it to the request.
  4. Send the JSON object to the API endpoint using the HTTP client.
  5. Get a response and see if it was successful or not.
  6. If it was successful, parse the response body from JSON to get the user Id.

This is a number of steps, and each one is error prone as there is no compiler or linter to help you. For example, if you sent the first name in a field in the JSON object called "first-name" and the API expected it to be "firstname" then the API call would fail at run time. If you forgot to add the access token, the API call would fail at run time. If you forgot to check the response, your code would continue to run and would fail at some point later on.

Creating a user with an SDK

An SDK on the other hand would implement most of this for you. It would have a class or other strongly typed definition for the user object, and would handle things like authentication and error checking for you. To use an SDK you would:

  1. Create an instance of the SDK class.
  2. Set the authentication token once on the SDK so it can be used for all subsequent calls.
  3. Create an instance of the user object, and set the properties.
  4. Call the SDK method to create the user, passing in the user object.
  5. If this fails, an exception would be thrown, otherwise the user Id would be returned.

Benefits of Application Programming Interfaces

APIs are the perfect way to expose a service to your internal infrastructure or the world via the internet. For SaaS (Software-as-a-Service) companies like Auth0 and Stripe, their APIs provide the services that their customers use to integrate with their applications. Internally organizations can build microservices or other internal services that different teams can use to build applications. For example, a company might have a user service that manages users, and a product service that manages products. These services would expose APIs that other teams can use to build applications.

By using a standard protocol such as REST you are providing the most widely used interface - development tools like programming language and many low/no-code technologies can call REST APIs. This means that your service can be used by any application, regardless of the technology it is written in.

Pretty much. every service should have an API if it needs to be called from an application.

Benefits of Software Development Kits

SDKs on the other hand are software components that provide wrappers over APIs. They make it easier to call APIs without making mistakes by providing things like type safety and error handling. If you use the wrong name for a field on an object, your compiler or linter will tell you (probably as soon as you type it with a red squiggly in your IDE). If you forget to add an access token, the SDK will throw an exception, but once set it can be used for all calls, and not need to be set every time. If the API call fails, the SDK can retry for you.

The benefit of an SDK is this hand-holding - it's a wrapper around the API that makes your life easier. An SDK takes nothing away from your API, developers can still call it directly if they are so inclined, but the SDK makes it substantially easier to use.

How and When to Choose Between SDKs or APIs?

As a provider of a service, there is no choice as such. You have to provide an API so software developers can call you service. Should you provide an SDK as well as part of your development process? Well, yes - it improves the experience for your users, and makes it easier for them to use your service. If you don't provide an SDK, then your users will have to write their own, and that's a lot of work for them. Keep your customers and users happy, right?

Conclusion

In this post we've looked at the differences between SDKs and APIs, and when you might use one over the other. We've seen that APIs are the interface to a service, and SDKs are wrappers around APIs that make them easier to use. We've also seen that APIs are the best way to expose a service to the world, and SDKs are the best way to make it easier to use an API.

Can I automate SDK generation?

The obvious question now is how do I create an SDK for my API. You could write one yourself, but why do that when liblab can automate SDK generation for you as part of your software development process? Check out liblab.com for more information and to sign up!