Forem: Infobip

You should build an SDK

Mike Elsmore — Thu, 22 Feb 2024 17:03:45 +0000

Over the last little while in my career, I’ve been either involved in building or building SDKs, especially here at Infobip with the huge array of tools we have on offer. And this leads me down a rabbit hole of wondering why organisations don’t build them by default once they reach a certain size if they follow an API-first design approach.

I’ve actually given talks on this subject a few times, if you want to skip reading, you can watch the last recording at

What is an SDK?

Let’s cover the basics: what is an SDK? The acronym itself means Software Development Kit, so it’s a toolkit for developing software. According to Wikipedia, the definition of an SDK is

A software development kit (SDK) is a collection of software development tools in one installable package. They facilitate the creation of applications by having a compiler, debugger and sometimes a software framework. They are normally specific to a hardware platform and operating system combination. To create applications with advanced functionalities such as advertisements, push notifications, etc; most application software developers use specific software development kits.

https://en.wikipedia.org/wiki/Software_development_kit

This means that I, and many like me who have treated SDKs as whatever the package manager installs, are a bit wrong (not totally, just a bit). What I mean by this, is that Client Libraries, like those that wrap an HTTP API, are not the SDK but a part of an SDK. An SDK is a collection of tools; this can include your client libraries, but also other dev tools. It could include testing tooling, webhook definitions, or even mathematical models for doing a task. Those of us who build primarily for the web or for mobile applications forget that they can also be physical SDKs. Game developers working on next-gen hardware regularly get access to kits like these for the PS5

At Infobip, we have a lot of SDKs, you can check them out here on our SDK page, but what I’ve been calling our NodeJS SDK is just a client library for now.

Why bother building an SDK?

Most people I know who are building SDKs are trying to enable a developer outside of their organisation, be it open source or proprietary, to consume the tools and products being built. I think this is wrong, and for a very simple reason, internal & external developers deserve the same tools.

Yes, external developers need help and ease of onboarding or use to engage with technology. But so do internal developers, it’s not uncommon for organisations to be running different services, with different technologies, and differing knowledge or experience levels.

Say the organisation you are in has some “legacy” systems running that no one actively works on but are used to grab information or tools that have been brought in over years and never updated. An internal client library providing a consistent set of functions to use them, as well as ETL tooling to make sure older standards are converted to the currently used ones, is a great SDK to build internally and manage. Or you could have REST, GraphQL, and WSDL systems that don’t have specification files or complete documentation on how to handle everything. A well-made SDK could solve that for teams.

Essentially, for internal and external developers, an SDK can lower the learning curve, which leads to speeding up implementation and provides consistency across everything being built.

How can you build one?

SDKs are meant to make life easier for the person using them, so the advice around developing them is rather straightforward.

If you are developing a wrapper library or code to be used or to be imported and used in a code base, follow the instructions and best practices for the languages or frameworks it’s being developed for. For example, if you’re creating it for the Express framework in NodeJS then you’ll need to follow the middleware pattern that it requires.

Where possible, use a namespace structure to allow people to only include the parts of the SDK they require if they do not need to use the whole thing. For example, fastify is a web framework in NodeJS and only the core structure needed for routing and requests are within the main fastify module. For everything else, that is expected of a full nuts and bolts framework, they’re included as an ecosystem of @fastify modules, like so

If you are developing a client library, follow a standard. Don’t hop about code styles, etc., as it’ll defeat the point of being easy to consume. And whenever you have to break the standard, make it known. Most languages and development environments allow you to easily see things like DocBlocks to explain why and also how to consume this edge case.

Let’s move on to something controversial among my peers. Personally, I think it is totally OK to use generators to produce client libraries. If you’re using standards like the OpenAPI Specification, you can use a plethora of generators to produce the first version of your client library codebase. And most importantly, where it isn’t fit for your purposes, you can modify the template, or completely extend the generator to give you the library you want. I definitely endorse this practice, as it’s something we do here at Infobip.

And now for some best practice tips, just to make everyone’s life a little easier to maintain them. Use version control on the code base that’s in-line with the language it’s been developed in. Additionally, where possible, use dependency management tooling and static analysis tools to make the maintenance and security risks manageable.

Write a URL Shortener in 26 Lines of Code with .NET Minimal APIs

Dino Lozina — Thu, 13 Jan 2022 13:16:45 +0000

I was looking forward to .NET minimal API framework for a very long time and now, it is finally out! Let’s dive into new version of .NET6 and answer the following questions:

What is .NET minimal API?
How to refactor existing URL shortener?
How to add dependency to service?
How to add endpoint to service?
Where are using statements?

🤔 1. Introducing .NET Minimal APIs

”Do you need all of this stuff just to shorten URL?”

This was a first reaction of a friend (who happens to be a Python programmer) when I showed him my first shortner example. "Yes" would have been a pretty accurate answer, but not the one that I’d be happy with.

There was a lot of boilerplate code compared to other frameworks.
One benefit is that the structure is already set up — very convenient when we have larger projects to tackle. On the other hand, not ideal when I need to create a small service as part of a microservices architecture.
Most SaaS providers are using microservice architecture for its scalability,smaller/faster deployments, and ease of understanding.

Take a look at the Flask API template:

In just 5 lines of code, we have our first endpoint! Single file, no other setup needed. All we need to focus on is the feature of this new service.

Now, let’s take a look at the .NET template. Out of the box we get Startup.cs, Program.cs, Controllers…a lot of boilerplate code. This could be unnecessary if the goal is to write one small service as part of a SaaS product or just a prototype.

Fortunately, .NET6 addresses this issue. Let's rewrite the previous example in .NET6 with a new template.

4 lines of code for our first endpoint and a single file. This is new .NET minimal API!

Back to my friend’s question - “Do you need all of this stuff just to shorten URL?”

No.
I can do better.

✂️ 2. Refactored URL shortener example

A while back, I wrote a post on how to create a URL shortener in .NET5), but I never imagined that I'd be able to rewrite it in 26 lines of code and a single file.

*Note: we actually have two files—we will get to the bottom of that in the fifth section, bear with me.

Refactored code:

You can find the previous URL shortener example in this github repository. There is nothing minimal about the codebase.

If we compare the old code to our minimal shortener, we will see the hidden complexity of the minimal API framework right away.

We start from scratch in the minimal API template and only introduce the dependencies we need. We can concentrate on the important stuff—the code for the requested feature.

Let's analyse the code and see what new things come with .NET6 that you could start implementing in your services.

⚙️ 3. Adding Dependencies

My service needs database, so I'm adding a dependency to LiteDB.

dotnet add package LiteDB

Usually, we would go to Startup.cs and set up our dependency. Since we don’t have one, the way to go is shown below on line 2. Same code, different position.

🔗 4. Adding an Endpoint

All the methods we need are in the app—or should I say framework?

MapGet(pattern, handler)
MapPost(pattern, handler)
MapPut(pattern, handler)
MapDelete(pattern, handler)

Check how to implement POST method and GET method in the example below.

The first parameter is route pattern, the second parameter is handler. The handler is delegate executed when endpoint is matched.

The Url object is record, also something new in .NET6. It could be a class as well, but I just wanted to shred couple of lines of code to get those 26 magic lines.

Data that our POST method (body of req) needs to contain is
defined by the record. (It is enough to send longURL, id will be set automatically by our db)

We have our database in the list of services that our app uses. The next step is to inject it into the endpoint. The delegate needs to have our database context to add data from the client to the database.

In the end, set up your service address and port.
And you are done!

app.Run("http://localhost:4000");

🙋 5. Where are using statements?

Global using statements is another feature I am happy with. Do you remember something like this on top of every file in your project?

using System;
using System.Reflection;
using System.Linq;
using System.Net.Http;
using System.Linq;

Implicit usings are hidden in auto generated file inside your obj folder. That file declares global using statements behind the scenes. If you go to project folder then go obj/Debug/net6.0, you will find a file titled “{ProjectName}.GlobalUsings.g.cs”.

Open this file, and see the content:

Since this is an autogenerated file, we can’t edit it here.
In our minimal shortener we have two packages (LiteDB, Hashids.net) that we depend upon, and we will actually need to place using statements in our Program.cs to use code from packages.

Instead, let's manually create a file that will hold our global using statements. This way, we keep our Program.cs free from all using statements.

It might be overkill in this particular example, but imagine adding more dependencies. It is a good option for keeping code clean.

🎊 So, is it possible? Of course! 🎊

Most of the time, we don’t need all the ceremony that we got with previous .NET webapi templates.

Now we have the option to start from scratch and add only stuff that we really need. Missing MVC Controllers? No problem.Add them later. Need Authentication? Same thing.

The template code has fewer files and a more intuitive setup for newcomers in the .NET world—this is probably one of the best benefits of this framework. I am really looking forward to seeing what future updates bring along.

If you enjoyed following along and building your own URL shortener in .NET6, keep an eye out for this blog!
In the next article, we will place this minimal URL Shortener in Docker and explore another essential piece of the tech stack.

Passwordless SMS Authentication 101 | Python Edition

aldin — Fri, 19 Nov 2021 17:32:16 +0000

Imagine yourself logging into an application without being required to create and remember a password. Well, not much to imagine, right? We all did it at least once before. There are plenty of approaches on how to implement this. One of those approaches is also by using passwordless SMS authentication.

What is Passwordless SMS Authentication?

Passwordless SMS Authentication enables application developers to offer authentication without having to remember login credentials. It allows users to enter their mobile device phone number to get a one-time code which can help them to log in.

With this user authentication technique, when, for example, a mobile user authenticates in an app for the first time, they are asked for their phone number. A one-time code is then sent from the developer's server-side app to that phone number as an SMS text message. The user then enters the code into the app and they are authenticated.

Let's say it's the first time for a user to use the app. An account will be created for that user. If not, the user will be authenticated to use the unique ID assigned by the identity provider. The authentication code sent to the user's phone number is not reusable, but it can only be used once, after which it expires. When the user visits the app again, a new code will be sent to their mobile phone number, which they can use to log in.

Thus, it will either:

save your users from the need to remember account passwords, or
add another level of security in case you want to use it as an add-on in the 2FA, 3FA, or MFA setup. There are suitable use-cases for either approach.

When (not) to use it?

So, when and why should you use (or avoid) this mode of authentication?

I guess the answer to this question varies depending on what are you trying to achieve. There are more elegant ways and which significantly reduce the risk of fraudulent activities such as account takeover, and there are enough articles out there talking about how and why should you go with either alternative approach.

To keep it completely real, if you are seeking ultimate security, you might consider using SMS simply as one of the layers of your multi-factor authentication process. Or you might just say: nope, I want something else.

If you're simply trying to do a simple integration that enables you to verify your user's phone number or really anything that is not that safety-critical, then sure, jump on board - it's easy to do it.

Ok, by now you should kind of be aware of what it is, and what might be the benefits or potential pitfalls. I guess it is safe to proceed with a bit of hands-on and see how this actually works in practice.

Passwordless SMS Authentication in Python

In this section, we will be discussing one approach on how to implement this authentication technique.

Infobip platform offers you a solution that you can use to send authentication messages. It provides official API libraries for different (at the moment of writing: Java, C#, PHP, Python & Go) programming languages.

You can find the list of various SDKs provided by this platform here. All our API-related SDKs are open-source and made available on GitHub. To learn more about the platform, visit its official documentation here. In this section, we will be demonstrating how to use the Infobip Python API library to send one-time passwords via SMS.

Package installation

First, you should install the infobip-api-python-client. You can install it using Python's pip package manager. Pip is shipped with Python, thus, you don't have to install it if you have already installed Python.

Open the terminal of your operating system and run the following command:

pip install infobip-api-python-client

The command will install infobip-api-python-client on your computer. You should get a success message similar to the one shown in the following image.

Configuration

Have you created an Infobip account? If not, please do so here, you'll need one in order to follow this to the letter. The next step should involve configuration and authentication. To properly set the configuration, you need a specific URL and an API key (both is provided to you when the account is created). You can find both on the homepage of your account.

To be able to use both of the above, simply click the copy-to-clipboard buttons and paste them into their proper locations in the config setup.

In order to initialize the Infobip 2FA API client and properly set the configuration for it, you should do the following.

Ensure that you substitute the right values of the various parameters in the above code. These include the API Base URL, the API Key, and the API Key prefix. For you to send the SMS successfully, these credentials MUST be correct.

While API Base URL and API Key you can simply copy from your account homepage, you have to set API Prefix manually. The reason behind this is that there are multiple authentication options, and you might choose not to use API Key but one of its alternatives. In case you chose to simply copy the key value available on your account, then you need to set the API Key Prefix value to App. That's it, you are ready to make API calls to the Infobip platform.

Application Setup

Before being able to send one-time passwords you need to set up the application and message template.

The application represents the service you are using it for. It is recommended to have different applications configured for different use cases or services. That is done by invoking the Create 2FA Application endpoint. Python lib you previously installed does it like shown below.

The last line reads the id of the created application so you can re-use it. Spoiler alert, you need it for the next step.

Message Template Setup

When the application is configured, you need to prepare the template for the message(s) you want to send. Let's see an example of how can you design the message body and the password (PIN) placeholder.

Similar to what you did in the previous chapter, now you read the id of the created message template. In order to actually send a password via SMS, we'll need both of the IDs - application and message template.

Sending SMS

Now that you have set up the application and designed the message template, let's send the code to the user via SMS. In order to do it, you can simply use the following:

Note that after sending the password you checked whether the message was sent successfully, and also saved another id. This one is going to be used in order to verify the user to whom you sent the SMS message.

Authentication Verification

So, you configured everything and sent the password. But how do you know whether the proper password was used by the user?
Well, obviously you somehow have to offer the user a way to put the password you just sent to him. After he does it, you simply need to call the following and check whether the response says the user is verified.

And if verified is true, that's it -your user successfully authenticated himself.

To conclude

Passwordless SMS Authentication can be used in various cases. Where needed, it can help developers to authenticate users without requiring them to remember a password. In other cases, it can be used to provide an additional layer of security on top of the basic username-password authentication.

It's really up to the application owner(s) to determine whether they need extra simplicity or extra security. This article is not going to go there, its sole purpose is to show you how easy it is to set it up.

Today we covered how it can be done via SMS, but Infobip also allows you to do utilize it via Voice and/or Email as well. Even Biometrics and something called Silent Mobile Verification are in play - more on it in one of the next articles.

Feel free to check this out and try it yourself after you create a trial account (needless to say; a free one). Unless you already have one, in which case you simply go and play with it.

How to schedule tasks in .NET? We've made it seem easy #2

Dino Lozina — Thu, 18 Nov 2021 08:25:29 +0000

Welcome to the second part of the series about "URL shortener in .NET". In the first post of this series we created simple URL shortener web service, and tested it manually with Postman. Check part one here or skip it if you only want to find out how to schedule services in .NET.

In part two, we want to expand functionality of our web service with some additional features, such as SMS reports.

This post aims to show you:

How to send SMS
How to easily add scheduler to our web service
How to send SMS periodically

Use my github to find a finished project and avoid the nuisance of writing the code yourself.

📱 First Step: Send SMS ✔️

For our SMS provider we will use Infobip. Please access our free trial self service account through this link. After grabbing our API key and URL you just need to implement client library in the project.

Library: (github)

dotnet add package Infobip.Api.Client

Then, place your user settings in appsettings.json, so that you can easily grab them through our web app.

Based on Infobip library, we will create method SendNotificationSms:

Let's go through SendNotificationSms(string smsNotificationMessage).

First, we set up the configuration we will send to SendSmsApi class.
Then create SmsTextualMessage by setting up Form, Destination and Text fields.
Finally, add created message to SmsAdvancedTextualRequest.

SendSmsMessage method from Infobip library will do the trick and send the message to our user:

var smsResponse = sendSmsApi.SendSmsMessage(smsRequest);

Now that the basic functionality is up and running, adding it to your scheduler shouldn't be a problem.

⏰ Second Step: Add scheduler ✔️

For this feature we will use Quartz.NET.
One could describe Quartz.NET as a full-featured, open-source job-scheduling system.

There are two important points you need to know; Job Scheduling and Job Execution.

1. Job Scheduling

Jobs are scheduled to run when a given trigger occurs, triggers support wide variety of scheduling options.

2. Job Execution

Jobs can be any .NET class that implements the simple IJob interface, leaving infinite possibilities for the work that jobs can perform.

Lets's add package to our project:

dotnet add package Quartz.Extensions.Hosting

Now, we have to configure and register our Quartz service. Use Program.cs for that. You can follow documentation https://www.quartz-scheduler.net/ on how to configure and register in detail.

In this code example, we try to keep Program.cs as short as possible, hence the extension method for our settings.

⏲️ Third Step: Send SMS periodically ✔️

Scheduler is all set up and now you need to add jobs. In our report feature we decided to send SMS messages daily, weekly and monthly.

Example project has three jobs defined in project Jobs folder.

Remember:

Jobs can be any .NET class that implements the simple IJob interface.

Example code below sends daily SMS report of how many URLs are shortened:

You may ask yourself: Where is the scheduled time in this code? How can I change it?

Well…that is the beauty of Quartz - it uses Cron expression which is easy to set up.
For example, we have moved scheduler setup to our application settings, so there are separate settings for every job in our application.

You can check out for various settings on cron triggers

In our example:

Cron expression: "0 0 8 ? * MON-SUN" -> Daily - MON-SUN on 08:00 CET for the previous day
Cron expression: "0 1 8 ? * MON" -> Weekly - MON on 08:01 CET for the past week
Cron expression: "0 2 8 * * MON#1" -> Monthly - first MON on the month for the past month

If you go back to Program.cs you will see how we grab and use this settings with our extension method.

Now our web service is ready to send scheduled reports to users.

Conclusion 🎉 🍾

It comes as no surprise that scheduling jobs in applications can be a really daunting work. Quartz makes it so much easier. Bare in mind that we just scratched the surface with our settings. There is a lot more stuff under the hood but probably this is enough for most of use cases.

The same thing can be said about our SMS notification feature. You don't need to write API request to Infobip platform. Just add library to your .NET project, set config, create your message objects and than send an SMS. It is also possible to expand this simple example and send reports with other
information channels, such as Email and Whatsapp.
Find other available options on Infobip Api.

Stay well,

Dino

Don't go OpenAPI first, go API first

Ivan Letenko — Wed, 17 Nov 2021 10:16:49 +0000

Despite the fact that API first approach has been around for many years, interest in it does not decrease and new articles are published.

There's a lot of interest thanks to the popularity of microservices and distributed systems, as well as actively growing as-a-Service solutions and add-ons marketplaces where developers can build and publish their applications and APIs on top platform's APIs.

Technical articles and presentations on API-first mainly focus on the technical implementation and use of certain tools, such as back-end code generation from OpenAPI specification, as well as rising interest to AsyncAPI specification that brings standard to event-driven architectures.

However, I think it is important not to confuse goals and methods of achieving them; remember the basics of API first!

What is API first?

First of all, it is a development process and strategy.

Think about your API as a product for other developers even if it's an internal service. Apply agile development principles to the API design and definition. This allows us to establish a contract for how the API is supposed to behave. This contract is crucial because it improves the interaction of developers and allows you to get a system consisting of a reusable, and extensible building blocks, which brings a great value for business.

An analogy is a test driven development (TDD), since it's also API first approach. Start with an interface, and the test will be the first consumer of your API.

The API contract itself can be specified in various ways which depend on the specifics of project and context.
It could be an OpenAPI specification, request/response JSONs, or interfaces.

For example, at Infobip most of the services define their API through Java interfaces and data models, on the basis of which the OpenAPI specification is generated, if necessary.
If you are designing an API for a web or mobile client of your service, design it as a product for external clients in order to avoid situations when you need to develop separate APIs for every new use cases.

The benefits of an API first approach are similar to agile development processes:

Fast feedback that allows you to make adjustments earlier while the cost of change is low;
No constraints inherited from wrong abstractions & data models, you better understand customer needs by collaboratively discussing and adapting APIs
Decoupling & parallelisation of work, teams can work independently having a common source of truth in the form of an API contract.

What is code first?

With a more traditional code first approach, the main functionality of the application is first developed and then an API for consumers and contributors is inserted on top of it.

This approach works well only for small APIs, mainly internal, when requirements are clear and stable.

Tools & Workshops We Use For 1600 Applications

Let's see briefly how we deal with internal & external APIs at Infobip. Infobip is a global communication platform that consists of over 1600 applications (service types) with hundreds of databases, data pipelines and support systems. More than 80 engineering teams work on. We have about 20 products that expose public APIs. At this scale it is vital for us to have reliable tools that synchronize and standardize service interactions while maintaining flexibility and speed of development.

As I mentioned, most of our internal services are written in Java or Kotlin. They expose their APIs as Java interfaces (we call them "connectors") and register them in home crafted remoting system. This system transparently builds HTTP APIs for inter-service communication. For non-JVM services we use sidecar pattern.

Dependent services can just import "connectors" and use them without worrying about implementation. In this way, the contract is defined and development is completely independent.

For APIs that should be exposed publicly we use a solution based on springdoc-openapi that generates OpenAPI specification from Java/Kotlin classes. Non JVM services can expose OpenAPI specification by themselves on a dedicated endpoint. Thus, regardless of how the specification is created, it is a public contract.

From that specification we generated public documentation and client libraries using OpenAPI Generator based pipeline. Library generation also helps maintain the quality and stability of specifications.

API docs & libs generation flow

What Works For Us At Infobip

Focus on API design before development;
Treat your API as a public product;
Tools & workflows are secondary.

In most cases, there is no need to dive into the complexity of OpenAPI right away.

OpenAPI has essentially become an industry standard and it is easy to use as a common language between components that guarantees interoperability and simplifies API management.

If you want to know more on this topic give some likes & comments ;)

How to write URL shortener in .NET5? We've made it seem easy #1

Dino Lozina — Thu, 11 Nov 2021 09:10:04 +0000

Welcome to our tutorial series, a place to be for those looking for a quick and efficient guide to writing URL shortener.

In this series we will try to show you how easy it is to write a service that shortens URLs with .NET5. On top of that, we will add an additional functionality - service will have to send an SMS when target URL is shortened and periodically send SMS reports.

Stick with me until the end and you will learn how to:

Create youtube like links for short URLs
Use embedded NoSQL database
Schedule web service, ex. send reports every day, week and/or month
Send SMS from our service

Just to give you heads up, this is by no means an extensive tutorial on how to build production grade shortening systems. For production grade systems we need to take into account scale and load. It would be nice to have some kind of analytics, but we have to start from somewhere, right?

Software engineering nowadays can be compared to playing with LEGO bricks. All the nice bricks are out there, we need to implement them in a smart way. We don't want to reinvent the wheel every time we start programming, so we're going to use a couple of packages to make all this magic happen.

First, we're going to need some SDK-s and tools:

For IDE we can use (https://code.visualstudio.com/)
We need .NET core SDK (https://dotnet.microsoft.com/download)
Postman (https://www.postman.com/downloads/)

On my github you will find the finished project so there's no need for you to write code yourself.

Once we have .NET framework in place we will just check if everything is working for us with (type in terminal):

dotnet --version

After the test we can create our template project:

dotnet new webapi -n "Shortener.Service" -lang "C#" -au none

*parameter -au none means there is no default authentication for our webapi

With this command we get template webapi project. Now that we have all things up and running let’s start with step by step guide.

🎮 First Step: Create controller methods ✔️

Remove default web api controller and create your own. For this simple example we will have one GET and one POST method.

Let’s dig into POST method. User will provide us with URL (simple UrlDataDto object) that needs to be shortened. We will store that URL we will store in LiteDB.

GET method needs a parameter shortUrl. If we have that shortUrl in our database, method will redirect us to “long” URL if request was made by browser. Request could also be made by “thin” client like Postman, so we will make sure that we return JSON with “long” URL. (In that case we don’t want to redirect)

💾 Second Step: Add database ✔️

As mentioned, we need DB to store our shortened URLs. For this small service we really don’t want to install DB or do something beforehand. Goal is just to “press play” and our app is ready to go.

dotnet add package LiteDB

This will give us small NoSql database, perfect for our proof of concept.

Now we need to link our application with DB:

⚙️ Third Step: Add services ✔️

As you can see, our controller is simple and whole business logic is in services. Let’s just check what we did in services.

First of all, let's create service that will write data to our DB.

Add to DB:

Get from DB:

We need logic that will shorten our URL. For this we can use cool package Hashids.net and get youtube like short ids. We can chose length and "salt" for our links. Check out hashids.net for short instructions.

For example, if we sent UrlDataDto:

{
  "url": "https://www.infobip.com/docs/api"
}

We get in response nice youtube-like short links:

{
  "url": "http://localhost:8000/V1oExr"
}

Let's add this feature:

dotnet add package Hashids.net

Method in service for encode:

As you can see, we will encode DB id and generate our short URL from that data. (We will use this service in POST method)

Method in service for decode:

Vice versa, on the other endpoint (our GET method) we will decode shortUrl to get id.

🧪 Fourth Step: Test with Postman ✔️

After dotnet build and dotnet run commands you are all set for manual test! Postman collections for you will find as part of the project, so that you can easily import.

POST:

GET:

That's all, folks! Or is it? 🎉 🍾

In part one of this series, we have created a simple URL shortener. We've showed you how to save data without installing database and generate short URLs with Hashids.net.

Application passed our manual test with Postman, and we have set up stage to implement notifications in our web service.

In part two of this series, we will learn how to:

Schedule tasks in .NET applications
Send SMS via Infobip platform

Infobip WebRTC - A Quick Setup & Test Guide

Adnan Arnautović — Wed, 10 Nov 2021 08:07:52 +0000

You know the usual developer drill - you sit down, ideas come and go, you filter the ones that work and write it all in a single go? Erm, not really!

When we start writing new software, there is always the stage of planning and deliberating about which technologies to use and which dependencies can help us make the best software for our use-cases and potential clients. This is where having the right tool is crucial for making the best decisions. If you are looking to integrate real-time communications into your application, we already have one of those tools in mind for you.

Why integrate RTC into your application in the first place?

You might ask yourself "Why would I use WebRTC anyway? Can't I just call someone over the phone?". Sure you can, but think about the different scenarios that could happen and the platform that could address them all. For instance, if you want to show someone a certain product or let them check something from a distance, you can use video calls over WebRTC to provide this service. Or let's say you're out on the road and you've just had an accident which you need to report to your supervisor. With WebRTC this could be as easy as having a two-minute video call.

Communicate across devices with multiple participants

By using WebRTC you can also employ many other devices, not just mobile phones, for your communication needs. If there is an office employee contacting multiple colleagues that work on the terrain, he or she can sit at their computer and still talk to the colleagues using their phones. If there's a need to talk to multiple people at once, WebRTC will make it happen quick and easy via the conferencing feature.

Record calls and keep track of communications

Recording calls, be it 1-on-1 or conference, is something not only useful, but also sometimes required by regulatory measures. With WebRTC you can choose to record your calls whenever you want and keep track of your communications when needed.

All of the above shows that with WebRTC you can harness the true power of your communications, implement more communication channels, and make the life of your clients and employees easier. If you want to test it out yourself, we've prepared a detailed setup guide. To be able to follow this showcase setup, please login to Infobip Portal.

What is Infobip RTC Showcase?

The Infobip RTC Showcase is a collection of simple apps implementing our Web and In-app Calls communication channel using WebRTC. These apps enable you to setup a simple WebRTC app and test its features out on your own, even change the code and experiment.

The following app examples are present in our showcase:

Kotlin
Swift
React Native
Angular
jQuery
React

Considering the main purpose of this app, you will also notice that the user interface is basic. This enables everyone to easily change the code in a matter of minutes and test out new things if they are interested.

Of course, if you are going to use the RTC Showcase and integrate WebRTC into your own app in the future, you will need to fulfil some prerequisites.

What to Know Before You Start?

To be able to use Infobip RTC Showcase, you first need to have certain things installed:

Node.js
Java, version 12

Next, you will have to set up the token application for the showcase applications. The token application is used to fetch the Infobip token you need for authenticating your identity when accessing Infobip's backend. Here you have two options, depending on the technology you want to test out with the showcase.

JavaScript Token Application

To be able to run the JavaScript-based token application, you will need to add a config.json file to the token/node folder with the following structure:

The HTTP_PORT, INFOBIP_API_HOST, and INFOBIP_RTC_TOKEN_PATH parameters are used to set the port on which your token app will run, and the host and path from which your token will be fetched. These values will be the same for everyone using our RTC showcase, although you can freely change the HTTP_PORT if the predefined port is taken. To be able to use the new port for the token application, do not forget to change the port in every respective application to the new one.

The more important parts of this config file are INFOBIP_API_KEY and INFOBIP_APP_ID. You can get both values from the Infobip Portal after you have logged in into your account.

To get INFOBIP_API_KEY you will need to access the "Manage API keys" site from the Portal dashboard (Manage API keys) and copy your chosen API key into the config.json file
To get INFOBIP_APP_ID you will need to access the "Apps > Web and In-App Calls > Applications" site (My Applications) and copy your chosen APP ID into the config.json file

When you have filled out the required information in the config.json file, you will need to do two more steps with the token application before you are ready to go onto the showcase applications. First go to the token/node folder through your terminal/command prompt and then:

Run npm install, which will install the packages needed for the token application
Run npm start, which will start the application on http://localhost:8080 (If you have not changed the port in the config.json file)

Now you can start running and experimenting with the showcase applications that can be found in the js/ folder, but if you want to be sure that the token application is running, you can run

If your token application is running, this will return a JSON object like the following

Java Token Application

To be able to run the Java-based token application, you will need to add two environment variables with the values for INFOBIP_API_KEY and INFOBIP_APP_ID. You can add the environment variables in several ways depending on the operating system you are using, and which approach you prefer. To set the environment variables through the terminal/command prompt:

For Unix-like operating systems (Mac OS and GNU+Linux)
For Windows operating systems

If we look at token/java/src/main/resources/application.yml, where you will find the following code

We will see that we can also easily change the HTTP_PORT value if needed. We just need to set the HTTP_PORT environment variable on our system, and our token application will prioritize that value.

After setting up the environment variables, we just need to run the following command from inside the token/java folder:

This will start the token application which is built with the Java Spring Boot framework. We can check if our token application is up and running by using the same command as the last time

If your token application is running, this will also return a JSON object like the last time

Keep in mind: If you want to run both token applications at the same time, you will need to change the HTTP_PORT value for at least one of them.

Showcase Applications

Showcase applications will use the token application to authenticate users on Infobip platform, so be sure to set up the token applications correctly before continuing.

Change Needed Configurations

If you have changed the HTTP_PORT inside the token application's configuration, you will first need to change the port for the token application inside showcase applications from 8080 to your preferred port.

Also, if you want to change the ports that the JavaScript-based showcase applications are using, you can do that by:

jQuery

Changing the HTTP_PORT value in js/jquery/app.js from 8010 to your preferred port

React

Changing the PORT value in js/react/package.json from 8020 to your preferred port

Angular

Changing the port option in the ng serve command in js/angular/package.json from 8030 to your preferred port

Add Google Services to Android Showcase Applications

To be able to receive notifications on incoming calls from Infobip showcase applications, you will need to add a Firebase configuration file to the app (step 3 here) named google-services.json to the app.

Depending on the project, you will need to add the google-services.json file in a different place:

Android Kotlin

Add the google-services.json file to android/kotlin/infobip-rtc-showcase-android

React Native

Add the google-services.json file to react_native/android/app

Here you can also make sure that you add the correct path to the Android SDK (Software Development Kit) on your computer on the React Native showcase application. You can set this in react_native/android/local.properties on the sdk.dir property.

Running JavaScript-based Showcase Applications

If you have gotten to this step and the token application inside token/node or token/java is running, then the following is straight forward. You just need to navigate to the folder for the chosen technology (be it jQuery, React, or Angular) and run the following

This will install and then run the application on the preferred port, which you can then access through your browser. To simply test out the application, you can start up two browser tabs and call the other user from one tab.

Keep in mind: If you are running the React or Angular applications, the page will reload automatically if you make any edits. You will also be able to see any lint errors in the console.

Running Mobile Showcase Applications

You can run the Android Kotlin and iOS Swift showcase applications as any other application through their respective IDEs (Android Studio and XCode) in the emulator. There is a known issue with receiving push notifications for incoming calls on subsequent runs on the emulator on all three mobile showcase applications (React Native, Kotlin, and Swift). This can be solved by wiping data from the emulator before running it again.

You can also run the app on a real device, although you will need access to the token application from the device itself. You can enable this by using the ngrok command, which allows you to expose your local port on the whole network. The following command will enable this:

Here you can also choose the preferred port to expose the token application.

Unlike the Kotlin and Swift showcase applications, the React Native application will require you to do one more step. Run the following inside the react_native directory:

or you can also use yarn:

The commands do the following:

Install needed dependencies
Start the application
Run the application on an Android emulator or your connected phone

Keep in mind: You can use either npm or yarn to run this application, but it is advised not to mix package managers to avoid resolution inconsistencies.

That's it. You're ready to go!

For now, through the RTC Showcase applications you can look at:

1-on-1 audio and video calls through WebRTC
Sharing your screen during the call
Calling a phone number using WebRTC
Joining conferences with audio and video
Sharing your screen during conferences

If you want to learn more about Web and In-Application Calls, you can visit Infobip's Voice and Video documentation for WebRTC.

Check if you already have access to our WebRTC Demo applications and try out the newest features over there:

To enable Web and In-App Calls, contact your dedicated Account Manager or our Sales team.

When you are ready to start integrating our SDKs into your own application, you are more than welcome to look at the reference documentation for various SDKs:

If you have any questions, we'd be happy to hear from You here!

Email collections under GDPR - The right way

Ivan Burazin — Mon, 01 Nov 2021 12:10:48 +0000

You're a certain someone who works on development of a client-oriented technical solution(s)? You probably want to have the best ways to communicate to those who are consuming your services in a robust way and scale it easily? If that's all you then keep reading.

This article has plenty of non-developer essential angles of email marketing covered, yet it emphasizes the need of conveying your messages properly. If you're not that interested in high-level why's and how's, but still are looking for the best solution (platform, APIs, SDK, portal, etc.) then I'd suggest you jump straight to the solution we linked for you below and start playing with it.

What is email marketing and why should you care?

In earlier years it was possible to collect and use consumer data with little restrictions (if any). Lately, however, with all the data privacy topics being in the focus it is now a service provider who must be careful on how is he approaching service consumers.

With email marketing, you can create long-lasting connections with your consumers. It's the process of sending commercial emails to those on your list who have given permission for us to contact them through email by subscribing - and people love getting great offers!

An example campaign would include an automated message sent at 9 AM every morning reminding customers about some exciting deals happening now only available via this link which will take 10 minutes off their purchase time - what are they waiting for!?

When it comes to small companies, it is one of the most cost-effective options. It's critical to realize that a large part of your success is entirely dependent on the email marketing software you select since they are ultimately responsible for ensuring that your emails get sent. If you're not cautious, you'll find yourself paying much more for fewer marketing options and poor email deliverability rates.

If you are looking for a reliable email solution, look no further than Infobip. Infobip platform handles plenty of communication channels, and email is just one of them. Check how simple it is to incorporate our solution into your product and choose for yourself if it meets all of your requirements. Our free trial

will assist you in familiarizing yourself with our solution, understanding integration, and recognizing the best possibilities with our solution.

How much do you need to worry about GDPR?

General Data Protection Regulation (GDPR) is a new set of European Union regulations governing the handling of personal data. Due to the constant development of the digital world, the GDPR is intended to bring prior data protection regulations up to date. It is designed to improve data protection inside the EU by implementing rules (and fines!) regarding personal data processing, acquisition, and storage.

The GDPR applies to your business if it processes, saves, or utilizes the personal data of EU people. Personal data includes email addresses, names, phone numbers, and behavioral data about your consumers. It is critical to remember that the rules apply to personal data transferred beyond the EU (to the US, for example).

Businesses may send email marketing to people only if the following conditions are met:

The person has expressly agreed.
They are a current client who purchased a comparable service or product and was provided with an easy method to opt-out.

The rise of social media has changed the way we interact with brands. In many cases, companies will send customers emails without their permission because they haven't unsubscribed from marketing lists or opted out - even if you don't want the communication! The best thing a person can do is check your inbox for any unsolicited messages and make sure that nobody else could have access to it either - only signing up using one email address should be enough protection against bad actors trying too hard to sell everything all at once… but let's face it: Most people just end up clicking "yes" anyways; whether on purpose or not doesn't really matter as long as there isn't an Automated Response waiting.

To be acceptable, however, they must have been provided a clear and simple option to opt out. This should be made available when their first data is taken and should be included in any future messages delivered.
This regulation implies that, although information may be given to current customers by email or text, it does not apply to new contacts or prospective consumers. Additionally, it does not apply to any promotional activity that is not commercial, such as political campaigning or charity fundraising.

Why is the Subscriber's consent important?

The GDPR imposes strict requirements on how you get, record, and maintain permission for marketing communications. In reality, this implies that people providing you with their email address must express permission actively and openly before you may send them emails.

Consent must be provided voluntarily. This implies that it cannot be accomplished via the use of a pre-ticked box. Apart from that, explicit permission is essential. This means that the client must understand what they are signing up for.

Take note that if you are contacted, you must provide evidence of the permission provided. It is critical, then, that you maintain a record of all consents granted by your subscribers.
You may send emails without obtaining permission. Rather than relying on consent, you may claim that you distribute newsletters to further your company's legitimate interests. However, and this is critical, the individual you are sending emails to should have some connection with you, such as having purchased one of your goods. It is up to each business to choose which approach is most appropriate for them - whether via consent or legitimate interests - and ensure compliance with the GDPR.

Email Marketing After GDPR implementation

Email marketing is a popular kind of advertising that was formerly very simple to deploy. However, with the implementation of GDPR, there is another area that needs careful attention.

For example, businesses must get express permission from their contacts before continuing to send them emails. This necessitates a more rigorous membership procedure that includes a double opt-in and an easy opt-out option and prohibits forced or compelled opt-ins.

A double opt-in verifies that users want to receive emails, filtering out fraudulent or negligent requests (for example, a user's failure to uncheck an automatically selected subscription box). If a customer gives their email address for a subscription, they will be required to consent to it a second time in their email.

The need for double opt-in serves as a safeguard for businesses that send promotional emails. Anybody subscribing to your emails should do so freely and without feeling compelled to do so in exchange for a specific product or service. Additionally, they should be able to unsubscribe from your email list at any moment without suffering any consequences.

To conclude

Well, we discussed that GDPR refocused marketers on established email best practices, further strengthening marketing campaigns for those already committed to providing superior customer experiences.

Now, these similar standards and guidelines advise subscribers how they will hear from you and how they want to communicate with you. As we've seen, this puts your marketing efforts in an ideal position to connect with a genuinely engaged audience, enabling you to deliver high-performing messages that impact your revenue. As marketers, we can now target and plan with more zeal, laser-focused on the information we have about our consumers. Now, their expectations have the potential to impact our companies significantly.
Moreover, using the right platforms can help create robust email solutions for their services, which helps in creating highly interactive email newsletters quickly and easily with robust solutions.

Feel free to sign up for our trial account to test out how we solve communication challenges! There you can experience how to integrate Infobipcommunication platform into your technical solution(s) and how it might help you expand the business.

Let’s Talk About Executing and Caching Queries with React Apollo

Danko Šimunović — Wed, 27 Oct 2021 16:45:31 +0000

Yep, you’ve guessed it. We’re going to talk about queries.

Let’s start with basics. The useQuery React hook is the primary API for executing queries when using Apollo Client in React. To run a query within a React component, we call the useQuery and pass it a GraphQL query string. When the component renders, useQuery returns an object from Apollo Client that contains loading, error, and data properties.

Apollo Query component is a deprecated way of executing queries. It’s a part of @apollo/react-components package and it is implementing Render props pattern. Render props are used for sharing code between React components using a prop whose value is a function. A component with a render prop takes a function that returns a React element. The component then calls this function instead of implementing its own render logic. In the case of Query component, we are using the children prop as a render prop. But because the children prop doesn’t need to be named in the list of “attributes”, you can put it directly inside the element. In the following example, we are passing a query prop, which is required.

Internally, Query component actually uses the useQuery hook and then calls the render props function with results returned from the hook. This means that we’re using the same options and are getting the same result object as when using the useQuery hook.

Cache-first, Ask Questions Later

Apollo is locally caching results for the queries by default. This makes subsequent executions of the same query extremely fast. This is called cache-first policy. We can define fetch policy on query level.

These are 6 supported fetch policies:

cache-first: This is the default fetch policy. If data is present in the cache, that data is returned. Otherwise, a query is executed against the GraphQL server and the data is returned after it is cached.
cache-only: Query is only executed against the cache. GraphQL server is never called.
cache-and-network: If data is present in the cache, that data is returned. But even then, a query is executed against the GraphQL server. If the response differs from what is stored in the cache, it will update the cache.
network-only: Query is executed against the GraphQL server, without first checking the cache. The query's result is stored in the cache in case the same query with a different fetch policy is being made elsewhere in the application.
no-cache: Behaves like network-only, except the query's result is not stored in the cache.
standby: Behaves like cache-first, except this query does not automatically update when underlying field values change. You have to update it manually.

There is also a possibility to define nextFetchPolicy option. This way, you can define fetch policy for the first query execution using fetchPolicy and then you can define fetch policy for the subsequent executions with nextFetchPolicy.

Apollo Client Behind the Scenes

Apollo Client acts as a facade to the underlying cached data. Behind the scenes, Apollo normalizes the data by splitting the results into individual objects and assigns a unique identifier to each object. These objects are stored in a flattened structure. Apollo then exposes an API to interact with the cached data. By minimizing direct access to the actual data using the facade/API, Apollo can normalize data under the hood.

Apollo can automatically update cache for:

Queries
Mutations that update a single existing entity
Bulk update mutations that return the entire set of changed items

Of course, there are use cases in which we have to manually update the cache:

Application-specific side-effects (something that happens after the mutation, but does not use data returned from the mutation)
Update operations that add, remove, or reorder items in a cached collection

Manually Updating Cached Data

Apollo supports multiple ways of reading and writing cached data:

readQuery / writeQuery
readFragment / writeFragment
cache.modify

With readQuery method, it is possible to run GraphQL queries directly on the local cache. If the cache contains all of the data necessary to execute a specified query, readQuery returns a data object in the shape of the query, just like a GraphQL server does. If some fields are missing from the cache, null is returned. Using writeQuery we can write arbitrary data to the cache for the specific query. It looks similar to readQuery, but it accepts data option.

Using fragments it is possible to read or update only parts of the cached data, unlike readQuery / writeQuery methods, which require a complete query. When using fragments to interact with cache, we can use readFragment / writeFragment methods. They require id option, which represents the unique identifier that was assigned to the object in the cache. By default, this identifier has the format <_typename>:<id>, but this can be customized. If there is no object with the specified ID, readFragment returns null. writeFramgent accepts data option, which represents data that will be written for the specified object and that conforms to the specified fragment.

With cache.modify it is possible to directly modify cached fields. This method requires the ID of the cached object to modify and a modifier function for each field to modify.

It is important to emphasize that any changes made with these methods are not pushed to the GraphQL server. If the current page is refreshed, these changes will disappear. Also, all methods trigger a refresh of all active queries that depend on modified fields.

Two Strategies for Updating the Cached Results

Besides manually rewriting cached data, there are two strategies for updating the cached results: polling and refetching.

With polling, we execute the query periodically at a specified interval.

Refetching is done by using refetch function that enables us to re-execute the query.

Apollo Client is a Powerful Caching Machine

In conclusion, one would have to agree that Apollo Client is a mighty caching machine. It’s equipped with a powerful caching mechanism that makes it easy to execute data queries quickly and efficiently. However, to make better use of its caching possibilities, one should get familiar with various methods of interacting with cache, cache setup and configuration.

I am a code-monkey and so are you

ZokiR — Wed, 29 Sep 2021 09:36:40 +0000

We have all been code monkeys. And yes, I admit - I was the monkey too. And now I am the monkey sometimes, code-monkey that is.
But what is a code-monkey? Is it a person, a role, or a strategy?
It is a programmer with a simple and basic skill set, according to Techopedia. It's the first step after you finish your education in IT and you get your first job as a software developer.
Now, I am a software engineer with 14+ experience in the industry and I look back to that time of the beginning when everything was simple.

I didn't have to think about the whole mechanism and how it will work, just one simple gear at a time. It was a time when I have entered the world of professional software development with very little knowledge of anything but the programming language I worked with (C# Love), an entry-level code-monkey some would say. I could focus on my for... loops, my class naming, etc.

If I had any questions, the "Engineers" had all the answers and the Senior Engineers were like Masters of their craft. When they lift a finger the solution appeared in front of you. And I was like 'I wanna be you...' and it happened, after many many highs and lows and years.

Today I think about mechanisms, systems, concepts, patterns, designs, and coding is the last thing on to-do list for any solution. I love that. I love being an engineer but it is far more than lifting a finger. I have to bleed and also do the monkey code dance.

Everybody in the development community has heard about the concept "Release early, release often".

In one of my previous jobs, the humans responsible for company vision had a "new" vision, a new application that could sky rock us high in earnings but we had to be quick, we had to prove that idea is good. The plan was to make a few basic killer features the app has to offer, release it and get some paying customers. A typical startup story. We (the team) were excited and started working on the app's architectural design. Then it happened. The architect weighted in: We needed to think about security, data storage, hosting, scaling, UX, etc.

Short story: we didn't release the app early. In fact, we didn't release it at all. We overengineered the damn thing. Sure, the junior developer who said to hardcode all we could and forget the concepts was WRONG, what a monkey!

We need both code-monkeys and engineers in development teams.
The natural path of learning and evolving as a software developer would be code-monkey (or junior) becoming an engineer. But how do we become engineers if we do only simple tasks with a basic skillset? We don't, we expand our skillset all the time. Learning new technologies, new design patterns, new solutions to our problems. So if we are doing that from the beginning aren't we also engineers? I think we are.

We are both; code-monkeys and engineers all the time because after we think about big peace, big scope, big ideas, solutions we come down to little parts where we use our simple skillset to make them work.

When we are pressed by our managers to fix a bug, it's always in a hurry, always some kind of fire we need to put out. Fix it now.. We'll rewrite it like we should… later! Come on, when do we honestly rewrite something if it works? Even in situations when everything is burning around us, we have to try to predict what could happen and how it will work down in the chain.
Only then we can call ourselves "Engineers". However, correcting that crucial buggy for...loop that started all the mess could be the time when you use the code-monkey.

Code-monkey is not a role, it is a strategy, a tool that you use in a day to do focused coding tasks.

This strategy is used after everything else is completed, the assessment, the diagrams, the planning, the engineering work, and the only thing is left is to code it, make it happen.
An experienced software engineers would say "that's the easy part", even a monkey could do it - but we do it. All of us, juniors, seniors, architects - no monkeys.

When I don't want to do a task break down, don't want to talk to people, don't want to think about the whole system, and just want to work on good explained task and write code. It's is my time for a Code-Monkey!

My question to you is: Are you a code-monkey?

Developers, Our Toolbelts Form Us!

Alexey Maltsev — Mon, 27 Sep 2021 10:56:38 +0000

Some time ago a headhunter from one of the biggest social networks in Russia contacted me and suggested an interview. I knew about their technical stack, however, and I declined the call since it’s not what I desired to deal with.

To my surprise the headhunter said “yeah, but I believe that for a professional software engineer the toolset itself doesn’t matter”.

Wow, that pissed me off, to put it lightly.

Well, maybe I took it too personally and it harmed my fragile nerdy ego, but it wasn’t just that.

From the beginning of my career in 2015 I always hear cool stories about T-Shaping, 10x-engineers and especially the requirement to be language-agnostic. At first glance there is nothing bad in any of it, especially being language-agnostic.

You think that all you need is to learn high-level approaches and specific tools don’t matter. All lollipops and rainbows.

Choosing The Tool That Makes You More Productive

The big gap here is that when you’re talking about being language-agnostic, no one mentions the productivity of a developer. If I was a chef in a restaurant, it’s obvious that I would be more productive in serving good meals if I worked only with my own knives, my own tools.

Why are software engineers in that case not the fortunate ones?

Programming is also a craft, so let the craftsman choose the instruments they need to accomplish tasks.

As a specialist, I’m really interested in solving specific and hard problems. I like challenges. Also I may prefer to work in specific business areas, like eCommerce, video-streaming, social networks, etc.

You guessed it: For each specific problem there is a set of good tools.

Developers work in teams. We’re not marathon runners - we are football players. And we get paid for things we deliver in specific infrastructure so there are a lot of reasons why we should use things we don’t like or we didn’t choose. Our employer or client chose them.

However, You are not a bad engineer if you don’t want to appreciate a corporation's choice and while searching for a job you filter companies by their technological stack also.

In fact, I think you might even be a better engineer and quite a visionary person, because you invest in your own future and carefully overcoming traps like maintaining someone else's legacy, which doesn’t develop you as a specialist.

Technology Agnostic Doesn’t Mean Forced Into Technology

So let’s change the definition. For me, being technology-agnostic means being able to switch to a new more effective thing, but not accepting everything that is dictated to you.

You are a specialist, you’ve got this mental model of what are pros and cons for each applied tool. As a specialist, share these insights with your current or potential employers without silent hating or hesitation.

Businesses are interested in cheaper and faster hiring of new employees, thus preferring the most popular and the most mature technology. That’s fair, but you as a software engineer should also introduce an “effectiveness” variable into their equation.

It is not only tools that I’m used to, maybe because I’m young and still “foolish and hungry”.

It's easy to get stuck with a painful tool, because you've gotten used to this pain.

I prefer tools that have an acceptable tradeoff between speed (including mine) and safety. In the last few years I’ve become a fan of limiting the ways to solve specific problems. For example:

Go provides simplistic features for concurrency and error-propagation.
Rust has a borrow-checker that protects you from race-conditions and so on.
And for me if a company has a monolithic technical stack, for example Java or .Net, there will always be cases where they don’t perform well and it’s a good point for experimenting.

More and more, I hear stories when a company hires high-graded developers and gives them the freedom to solve problems with tools that they think are more appropriate.

This is quite a sweet approach when companies have that kind of confidence in developer’s professionalism, that they don't care how the problem will be solved. I won’t lie, as a software engineer, I dream to be so good at my job that I can do just that.

It’s quite valuable when a new software engineer brings improvements into a company's technical stack. This new blood can properly justify their decisions, when they consciously choose the technology - the tools that form them - during their career.

Code that writes code for you -wait what?

dsvigir — Wed, 01 Sep 2021 09:45:28 +0000

I've spent six years as a team leader and one of my responsibilities was performing technical job interviews with potential candidates for our team/company. Soon I've noticed a pattern. Candidates working with JAVA programming language were not using https://projectlombok.org/ on their projects. Yes, I'm aware it doesn't qualify for the drama-of-the-year category, but this was quite a surprise for me. Projectlombok.org was such an integral part of my daily work, one of those simple life hacks you are happy to share. So why is this simple code-generator so important? Well, if you want to join the church-of-release-from-writing-boring-and-repetitive-code, keep reading!

Why would you want to use code-generator?

Simply put, if you want to spend your coding time on something new and challenging, code-generator can save you time spent on repetitive (or boring, as some may refer to it) coding. This fact alone can certainly speed up development and benefit the project or company you're working for. But, as always, first there are some issues to deal with.

A matter of Trust

"I only trust code that I wrote, should I trust generated code? " (Unknown Developer)

The idea of using code generation as a standard operating procedure within our team was first brought up in one of our meetings. We soon figured out that:

We wanted to write our own code
We trusted our code more than some auto-generated sequence

We discussed our coding guidelines, the fact that we do not like how generated code look, how it might be hard to read and understand, it might break OOP principles, clean code principles and so on. Most of the issues we've had with code generators were trust related, and this lack of trust was the first obstacle we wanted to address.

Since trust takes time, we decided that our first use case should be something simple. There are a lot of really good, simple and helpful code generators.
This blog should help you understand why and when you should use code generators, give you some example how and where we use it and give you overview of some simple code generators that have different purposes.

Reflecting on my experience and thinking about code generators seems to me that when and why to use it is highly dependent on what project are you working on, what programing language are you using, what are the use cases, how complex is part of code that you want to replace with generated code.

Where do I Start?

Remember Project Lombok? Let's give you an overview and see how it can help you to avoid repetitive, boring and error prone coding.

Let's say we want to implement simple immutable class that will represent Car. It could look something like this:

So, to achieve immutability, we needed to write constructor with null checks for fields that are not permitted to be null and get methods for each field. We also override toString, which is something we usually do to be able to print some instance of this class to get human readable data for logs, debugging and so on.

This is something that needs to be done, but it is repetitive and boring, not to mention error prone. If we lose focus we could easily forget to add Object.requiredNonNull for field that must not be null. The bottom line is that we want to speed this up and let code generator do the writing for us.

Now let's see how this class looks when we use Lombok:

It's easy to see that the amount of code we need to write is significantly lower, not to mention that the class looks cleaner, as we also removed a lot of boilerplate code. We really don't need it in in source file to know what this class contains - Lombok annotations will tell us that.

What did Lombok annotations do for us:

@RequiredArgsConstructor - generates constructor with all fields that have final modifier on them.
@Getter - generate get method for all fields in class
@ToString - overrides toString method which will use all fields to generate String representation of this class

This is just a small subset of what Lombok can do for us. However, one should be aware that Lombok does not generate new source code (new Car.java) and it doesn't replace anything in original Car.java It injects necessary code during compile time into bytecode of compiled Car.class. You can always decompile Car.class if you want to inspect what exactly Lombok generated.

Is there anything I shouldn't do with code-generator?

Code generates can be really powerful. You could probably write most of the project code to be self-generated, and describe project using semantic needed for a code generator to generate project source code without writing a single line of project code yourself.

It's easy to get carried away and spend your time thinking about projects you could do with code generator rather than finishing the existing ones. Do not auto generate everything that can be auto generated - start with tackling simple, repetitive and boring code sequences. Try and do proof of concept and see where does that lead you to.

Some general tips to go by which might point you into direction this is where I should not use code generation. If you are doing proof of concept or you are already using code generation for some time:

If you find yourself in need to modify generated code
If you find yourself in need to inspect generated code
If you find yourself constantly working on code generator because it is lacking some features
If maintenance of code generator is taking considerable time compared to gain

PROs of using code generators

Less errors - code generators do not make mistakes. They will do their job and generated code will be the same no matter how many times they generate it. Code generator doesn't get tired and it doesn't lose focus like humans do.
Time saving - generating code is fast, much faster than any human can write code. More repetitive tasks and code you need to write means more time you save using code generators.
Expected output - generated code will always be the one you are expecting. Naming, coding principles, the way code works will be something that will be same no matter who is using it. If a code is written manually by different developers, this kind of consistency usually cannot be achieved.
Cool, I don't need to write this code again - as developers, we often found ourselves writing similar code all over again. This can be really boring, and in the end we should have fun when writing code, and code generators can provide us extra time to write a more meaningful code.

CONs of using code generators.

We need to modify code generator again - our code generator requires constant maintenance. We are finding new use cases for it and it is getting more convoluted and time consuming to maintain it.
Code generated is not optimized - if your code and project needs to squeeze every bit of performance, then code generators might be obstacle. Usually, to optimize code for performance you do it manually, change architecture of code, maybe change order of code lines or just rewrite it completely. If your code is generated, this can be really hard to do, and could require extensive modification on code generator you are using or it just might not be possible.
Generated code is a mess - although this technically goes into cons, this should not be your concern and you should not be worried about how the code looks. Code should be something that works for you, strictly utilitarian.

Simple code generation in our project

Our project is microservice oriented so we have multiple instances of various services and uptime of those services is very important. We collect over 200 metrics data and constantly monitor what is the state of our system/services.

Most of our metrics are custom made. As the number of metrics increased, we found our self spending a lot of time writing a code that collects metrics required for some feature we were working on.

This was our scenario:

Writing repetitive and error prone code
Writing it for almost every new feature we added
It was boring and it was slowing us down

Let's say now we want to implement a set of metrics that will count how many red and blue cars we sold:

This is how our base for code generation looks like. Here we used our custom defined annotations (@MetricSchema, @MetricCounter) as metadata that we needed as an input into code generator and our custom defined metric type(ResetableCounter).

This is how part of our generated source code looks like:

This generated class will be used as our metric object when instanced to collect metric on our application. It has all that we need to start collecting and reporting this metric.
We have static factory method that will help us to instance metrics and we have methods to increment, reset metrics and method to retrieve metric value.

Next example shows us how to use this generated code to collect metrics:

We are using https://github.com/jtwig/jtwig-core as a code templating engine, and this is how our template looks like. Without going into too much details about jtwig, this template allows us to generate CarMetric class from AbstractCarMetric. This is how we generate all the metric classes that we need.

This is relatively simple code generation. Considering that we are writing and collecting a lot of metrics on our project, we did this to release us from the need to write metrics ourselves.

Some Simple Code Generators

https://projectlombok.org/ — we discussed it earlier, it has a lot of functionality, most commonly used functionality is going to free you from writing repetitive boilerplate code (constructors, getters and setters and so on)
https://www.jooq.org/doc/3.14/manual/code-generation/ — this code generator is used in conjunction with library itself. Main job of this code generator is to inspect your database schema and generate classes that represent object model of your database. This is very common case for code generators as writing object model for database manually is very repetitive, error prone and time consuming.
https://developers.google.com/protocol-buffers — protocol buffers are usually used in conjunction with https://grpc.io/docs/what-is-grpc/introduction/ but they do not have to be used for that exclusively. This is example of language agnostic code generator that can generate code from defined protobuff semantic for different programing languages.

An advice at the finish line — Start with baby steps

Code generators are a broad and complex topic. It might not be clear where you should start with code generators because use cases for them are virtually endless. You might end up using code generator and walk into something that in the long run will be a really big burden for the project you are working on.

If you are just starting to use code generators, start with baby steps. Find your simple use case (repetitive, boring, error prone coding), do your research and find if someone already solved your problem.

When you decide on which code generator you are going to use and what use case you want to cover, do proof of concept for it and move forward from there. Choose wisely I hope this blog post will be of help on your coding path!