APIs have become a rapidly growing field where every software you use today will involve API to some extent. API-related jobs are also rising to new heights every year. With each passing year, the security concerns around poorly written web APIs are also on the rise, which is why there is a need to know and practice some of the REST API design best practices to prevent such instances.
I’ve been working with Restful APIs for some time now and one thing that I love to do is to talk about APIs.
So, today I will show you how to build an API using the API-First approach and Design First with OpenAPI Specification.
First thing first, if you don’t know what’s an API-First approach means, it would be nice you stop reading this and check the blog post that I wrote to the Farfetchs blog where I explain everything that you need to know to start an API using API-First.
Before you get your hands dirty, let’s prepare the ground and understand the use case that will be developed.
If you desire to reproduce the examples that will be shown here, you will need some of those items below.
To keep easy to understand, let’s use the Todo List App, it is a very common concept beyond the software development community.
#api #rest-api #openai #api-first-development #api-design #apis #restful-apis #restful-api
APIs can be as simple as 1 endpoint for use by 100s of users or as complex as the AWS APIs with 1000s of endpoints and 100s of thousands of users. Building them can mean spending a couple of hours using a low-code platform or months of work using a multitude of tools. Hosting them can be as simple as using one platform that does everything we need or as complex as setting up and managing ingress control, security, caching, failover, metrics, scaling etc.
What they all have in common are three basic steps to go from nothing to a running API.
Each of these steps has its own set of tools. Here are some I’ve used and popular alternatives.
REST is the most popular API interface and has the best tooling. Our design output for REST services always includes an OpenAPI specification. The specification language can be tricky to get right in JSON (how many curly brackets?) or YAML (how many spaces?) so a good editor saves a lot of time.
Four popular ones are:
I’ve only used Swagger and Postman but both Insomnia and Stoplight look interesting. All of them offer additional functionality like documentation, testing and collaboration so are much more than just specification generators.
#api #apis #api-development #restful-api #rest-api #development-tools #app-development-tools #developer-tools
The REST acronym is defined as a “REpresentational State Transfer” and is designed to take advantage of existing HTTP protocols when used for Web APIs. It is very flexible in that it is not tied to resources or methods and has the ability to handle different calls and data formats. Because REST API is not constrained to an XML format like SOAP, it can return multiple other formats depending on what is needed. If a service adheres to this style, it is considered a “RESTful” application. REST allows components to access and manage functions within another application.
REST was initially defined in a dissertation by Roy Fielding’s twenty years ago. He proposed these standards as an alternative to SOAP (The Simple Object Access Protocol is a simple standard for accessing objects and exchanging structured messages within a distributed computing environment). REST (or RESTful) defines the general rules used to regulate the interactions between web apps utilizing the HTTP protocol for CRUD (create, retrieve, update, delete) operations.
An API (or Application Programming Interface) provides a method of interaction between two systems.
A RESTful API (or application program interface) uses HTTP requests to GET, PUT, POST, and DELETE data following the REST standards. This allows two pieces of software to communicate with each other. In essence, REST API is a set of remote calls using standard methods to return data in a specific format.
The systems that interact in this manner can be very different. Each app may use a unique programming language, operating system, database, etc. So, how do we create a system that can easily communicate and understand other apps?? This is where the Rest API is used as an interaction system.
When using a RESTful API, we should determine in advance what resources we want to expose to the outside world. Typically, the RESTful API service is implemented, keeping the following ideas in mind:
The features of the REST API design style state:
For REST to fit this model, we must adhere to the following rules:
#tutorials #api #application #application programming interface #crud #http #json #programming #protocols #representational state transfer #rest #rest api #rest api graphql #rest api json #rest api xml #restful #soap #xml #yaml
At Moesif, we primarily market to developers and other technical audiences like product managers and developer relations teams looking to make their own developer platform successful. Getting developers to adopt your API or tool is hard and requires heavy investment in experimentation and measurement in order to achieve the results you’re looking for. At the same time, much of the online advice you hear for B2C or B2B marketing simply won’t work when marketing to developers. This article outlines much of the findings we’ve seen as we grew Moesif from 0 to now over 5,000 companies including Deloitte, UPS, and Radar.
Before jumping into things you should be trying, let’s review what’s so special and hard about marketing to developers. Most developer-focused companies are founded and led by developers themselves, so you would think figuring out things like product marketing should be easy right? After all, you’re just marketing to yourselves. Just like any audience, there is no single developer persona.
Fast and iterative experimentation is critical to recoup any investment in paid ads. If you’re not diligently tracking your metrics, you can easily run up your cost per acquisition (CPA). However, what do you actually measure against for a developer tools company? Accurate attribution can be complicated since for many developer-tools, the majority of the value and magic your product creates is via an API or integration, not via a mobile or web app. This means a user who signed up and clicked around your website isn’t necessarily a converted user. Yet, there is some intent based on the content or areas of the product a user is looking at. For most developer-first companies, we recommend looking at a metric such as developers who made their first API call. Later, you can define additional funnel stages such as developers who made more than X transactions through your API or developers who used Y different features. Additional complication comes from attributing back to the marketing channel since now you have to instrument both your website to track the acquisition channels a developer went through and then linking that to what the developer did with your API.
Most social ad networks are designed to target general consumers based on personal demographic data, not developers. You can target consumers with these networks with simple Yes or No filtering. Such as Does the person live in San Francisco or Is the person aged between 18 and 24 years old. This means if you’re a pizza shop in San Francisco, it’s relatively easy to set up Facebook ads to target college students aged 18 to 24 who live in or around San Francisco. This demographic may be ideal late nite pizza customers.
For developer’s there is no single “is developer” demographic that can be answered via a simple Yes or No question. You could attempt something like _Is their college degree Computer Science”, but software engineering is a career with a variety of educational paths and does not always require a computer science degree. Even if you could match on a person’s title, software engineering is an ambiguous role with varying responsibilities. Some engineering develop embedded systems for cars and drones, some software engineers are focused on building internal data analytics infrastructure, others are integrating billing APIs.
Many developer tools are in horizontal markets targeting a variety of markets rather than singling out a specific industry, but they solve a specific problem. Like enterprise sales, this means you need to target the right developer who will have a use for your devtool and champion it internally.
The art of selling to developers is similar to most complex enterprise sales processes which have a multitude of stakeholders involved. For devtools, the number of stakeholders can be even more than traditional SaaS since you may have architecture review, security sign off, implementation, etc. This is because many times developers are checking out your tool or product for a corporation, not just for themselves. Handling these complications can be rolled into your marketing plan, rather than waiting until last minute objection handling.
Technical audiences are by nature skeptical. They love to build things, not buy services. This creates inherent biases as they are exposed to third party solutions. Due to internal political struggles, some developers may have resentment or bias against sales and marketing teams. This makes direct outreach less effective. While it does work for certain top-down sales strategies such as for selling security software to CISOs, many devtools are trying to get an individual developer to first adopt the tool and then grow from there.
One of the most effective ways to attract developers to your platform (rather than filling their email box) is with inbound marketing. Inbound marketing is the art of attracting or pulling in developers to adopt your platform rather than forcibly pushing your platform on to them. There are a variety of techniques for inbound marketing from SEO to referrals, but the focus of this article is paid ads.
As mentioned, developers are usually skeptical of traditional marketing activities. Whether this is an email from a SDR that is two paragraphs too long or a huge banner that says “Sign up now.” Being numbers-driven, they would rather cut through the bullshit and explore how something works themselves rather than be told how something works by a non-technical person. Developers also love to tinker and discover. That feeling of discovery though is a strong emotion. Think of the last time you discovered some new life hack or website that became your favorite and told your friends. That’s what inbound marketing leverages.
Effectively inbound marketing makes it appear that the developer discovered a new tool or platform on their own when in fact they were marketed to.
When done right, paid ads can drive adoption with low acquisition cost, but it requires much more planning and support than simply dumping a bucket of money on Facebook ads. If done incorrectly, you’ll still be pushing your product. The key is to be natural.
First you should decide on the goals of these initiatives, such as:
Once you have your core objectives, you can lay out a content strategy to be used for social ads just like you would create a SEO strategy and keyword planner. Content is the number one item that makes your ads appear inbound. Content should be genuine and interesting to developers, but still relatable to the specific pain your tool solves.
It’s a fine line how specific you want to be. If you go too broad, then you’re not really pulling in the right developers that would adopt your solution. You can’t push out content that tells a developer to sign up when they don’t yet recognize they even have a problem. The way to solve for this is mapping the above goals to content that targets various stages of buying funnel:
#developer marketing #api best practices #developer relations #api adoption #developer advocacy #developer advocate #api product #api evangelist #api program #developer journey
In the API economy, a successful service can gain popularity and be utilized in ways unpredicted and often inconceivable by its original owners. The very flexible nature of the technology opens many doors, including business collaborations, reuse in third-party products or even conquering hardware barriers by reaching a spectrum of devices.
Taking the builder’s perspective
Important note: Most of the time API consumers are not the end-users but rather the app developers. Any new venture ought to be supported with excellent learning resources and descriptive documentation. These things combined will ensure a top-notch developer experience and encourage adoption of your product, increasing its visibility in the market.
More than the revenue
While in the simplest scenario, the most popular API business model is revenue via service charges, there are several other goals:
#api #api-development #api-integration #restful-api #api-based-business-model #api-first-development #automation #rest-api