DEV Community: Elliot Brenya sarfo

How to Design Quality APIs

Elliot Brenya sarfo — Thu, 04 Sep 2025 01:29:58 +0000

I think most API design advice is too technical. Developers get sidetracked by discussions about what "real" REST is, whether HATEOAS is the right thing to do, and so on. In this post, I'll try to cover everything I know about designing good APIs.

When designing an API, it is important to balance clarity and flexibility.

This is true of systems, and it is even more true of APIs: good APIs are boring . An interesting API is a bad API (or at least it would be better if it were less interesting). APIs are complex products to their developers, taking a lot of time to design and improve. But to the people who use them, they are tools they need to do some other task. All the time they spend thinking about the API instead of thinking about the task is time wasted. From their perspective, the ideal API should be so familiar that they can more or less use it before they even start reading the documentation 2 .

However, APIs are very different from most software systems in that APIs are hard to change . Once an API is published, people start using it, and any changes to the interface will break their software. Of course, it is possible to make changes . But (as I will discuss below) every change comes with a significant cost: every time you force users to upgrade their software, they seriously consider switching to a different, more stable API. This greatly incentivizes API designers to design their APIs carefully and get it right the first time.

This pressure creates an interesting dynamic for API engineers. On one hand, they want to create the simplest API possible. On the other hand, they want to use smart solutions to maintain flexibility in the long term. In short, API design is a trade-off between these two incompatible goals.

We don't break user space

What happens when we need to make changes to the API? Additive changes, such as adding a new field to the response, are usually fine. Some consumers will break if they get more fields than they expected, but I think that's irresponsible behavior. API consumers should be expected to ignore unexpected fields (reasonable typed languages that parse JSON do this by default).

However, you cannot remove or change the types of fields. You cannot change the structure of existing fields (for example, move them user.addressto in user.details.addressa JSON response). If you do, every block of code that depends on those fields will immediately break. Consumers of that code will report it as a bug, and the maintainers of the code will rightfully be angry at you for intentionally breaking their software.

The principle that applies here is in the style of Linus Torvalds' famous slogan: WE DON'T BREAK USER SPACE . If you're an API maintainer, you have a kind of sacred duty: you must avoid hurting downstream consumers. This law is very strong because so many programs depend on so many APIs (which in turn depend on upstream APIs, and so on). One careless API maintainer high enough upstream can break hundreds or thousands of programs downstream.

It's never a good idea to change an API just because it's prettier or because it's a little ugly. A famous example: the "referer" header in the HTTP spec is the word "referrer" with a typo, but it wasn't changed because we're not breaking user space.

Making API changes without breaking user space
Frankly, it's hard to think of examples where an API truly requires breaking changes. But sometimes the technical value of a change is so high that you decide to take the risk and implement it anyway. How do you change an API responsibly in these cases? That's where versioning comes in .

By versioned APIs, we mean that we will handle both the old and new versions at the same time. Existing consumers can continue to use the old version, and new consumers can decide to use the new version. The easiest way to do this is to add something like to the API URL /v1/. OpenAI's chat API is located at v1/chat/completions , so if the company decides to completely redesign it, they can do it in v2/chat/completionswithout breaking anything for existing consumers.

Once the old and new versions are running at the same time, you can offer users the opportunity to upgrade to the new version. This will take a long time : months or even years. Even if you have banners on your website, documentation, emails, and headers in your API response, when the old version is finally removed, there will still be a lot of angry users complaining that you broke their software. But at least you tried to do something about it.

There are plenty of other ways to implement API versioning. The Stripe API implements versioning in the header and allows accounts to set their default version in the UI. But the principle remains the same — all Stripe API consumers can be confident that Stripe hasn't decided to break their apps, and that they can upgrade versions at their own pace.

I don't like API versioning. I think it's a necessary evil at best, but it's still an evil. It confuses users, who have a hard time finding API documentation without checking that the version selector matches the version they're using. And it's a nightmare for maintainers. If you have thirty API endpoints, each new version adds thirty new endpoints to support. Soon you have hundreds of APIs to test and debug, and support for their users.

Of course, adding a new version doesn't double the size of the codebase. Any reasonable API versioning backend has some translation layer that turns the response into one of the versions of the public API. Stripe has something similar : the business logic itself is the same for all versions, so versioning is only taken into account when serializing and deserializing parameters. However, such abstractions always leak.

The success of your API depends entirely on the product

The API itself doesn't do anything. It's a layer between the user and what they actually want. In the case of OpenAI, the API is the ability to do inference using a language model. In the case of Twilio, the API is sending SMS messages. No one uses an API just because the API itself is beautifully designed. They use it to interact with your product . If your product is valuable enough, users will switch even to a terrible API.

This is why some of the most popular APIs are so terrible. Facebook and Jira are notorious for having terrible APIs, but it doesn’t matter if you want to integrate with Facebook or Jira (and you do), you’ll have to spend time understanding them. Yes, it would be great if these companies had better APIs. But why invest the time and money if users still want the integration? Writing good APIs is hard.

In the rest of this post, I'll give a lot of specific advice on how to write good APIs. But it's worth remembering that most of the time, it doesn't matter. If your product is desirable and popular, a barely working API will do; if it's unloved, a good API won't help. API quality is a non-essential feature: it only matters when a user is choosing between two essentially equivalent products.

However, the issue of API availability is a completely different story. If one product has no API at all, then that is a serious problem. Technical users will demand that you implement some way to integrate through code with the software they buy.

Poorly designed products usually have bad APIs

A technically sound API won't save a product that no one wants to use. However, a technically poor product makes it nearly impossible to create a beautiful API . This is because API design is typically based on the product's "core resources" (e.g. Jira resources are issues , projects , users , etc.). When these resources are poorly implemented, the API becomes ugly.

For example, consider a blogging platform that stores comments in memory as a linked list (each comment has a field nextpointing to the next comment in the thread). This is a terrible way to store comments. A naive solution for attaching a REST API to this system would be something like this:

GET /comments/1 -> { id: 1, body: "...", next_comment_id: 2 }

Or, worse, like this:

GET /comments -> {body: "...", next_comment: { body: "...", next_comment: {...}}}

This example may seem silly, because in practice we would simply iterate over the linked list and return an array of comments in the API response. But even if we were willing to do this extra work, how far would we iterate? In a thread with thousands of comments, wouldn't it be impossible to get any comments after the first few hundred? Would your comment retrieval API be forced to use a background task, turning the interface into something like this?

POST /comments/fetch_job/1 -> { job_id: 589 } GET /comments_job/589 -> { status: 'complete', comments: [...] }

This is how some of the worst APIs are created. Technical limitations can be cleverly hidden in the UI and exposed in the API, forcing API consumers to understand the system architecture much more deeply than necessary.
Authentication
You should allow people to use your APIs with a long-lived API key. Yes, API keys are not as secure as short-lived credentials like OAuth (which you should probably support, too). But that doesn't matter. Every integration with your API starts life as a simple script, and using an API key is the easiest way to get a simple script working. You should make it as easy as possible for developers to get started with your API.

While API consumers will write code, many of your users won’t be professional developers . They might be salespeople, product managers, students, hobbyists, and so on. When you’re an engineer at a tech company building an API, it’s easy to imagine that you’re building it for people like you: competent, professional, full-time software developers. In fact, you’re not. You’re building it for a broad cross-section of people, many of whom have trouble reading or writing code. If your API requires users to do something complicated, like perform an OAuth handshake, many of them will have trouble.

Idempotency and retries

When an API request succeeds, you know what it was trying to do. But what if it failed? Some types of failures tell you what happened: 422 usually means that the failure occurred during the request validation stage, before any action was taken 3 . But what about 500? What about a timeout?

This is relevant for API operations that perform actions . If you call a Jira API to create a comment on an issue, and the request returns a 500 or times out, should you try resubmitting it? You don't know for sure whether the comment was created, because the error may have occurred after the operation. If you retry, you may end up posting two comments. And it's even more important when there's more at stake than a Jira comment. What if you're transferring money? Or prescribing medication?

The solution to this problem is idempotency , the ability to safely repeat a request without creating duplicates. The standard is to support an "idempotency key" in the request (say, a user-defined string in a parameter or header). When the server receives a "create comment" request with an idempotency key, it first checks whether it has seen such an idempotency key before. If so, it does nothing; otherwise, it creates the comment and then stores the idempotency key. This allows the user to send as many retries as they want: if they all have the same idempotency key, the operation will only be performed once.

How should the key be stored? I've seen cases where it's stored in some kind of durable, resource-bound way (like a column in a table comments), but I don't think that's strictly necessary. The easiest way is to store it in Redis or some similar key-value store (where the key is the idempotency key). UUIDs are unique enough that they don't need to be scoped to each user, but that's fine. If you're not doing payments, you might even want to expire them after a few hours, since most retries happen right away.

Do we need idempotency keys for every request? They are not needed for read requests because double reading won't do any harm. They are also usually not needed for delete requests because if you delete a resource ID, that ID serves as an idempotency key. If we send three requests DELETE comments/32 in a row, we will not delete three comments. The first successful request will delete the comment with ID 32, and the remaining requests will return 404 because they can't find the already deleted comment.

In most cases, idempotency should be optional. As discussed above, you want to make sure your API is understandable to non-technical users (who often find idempotency a complex concept). In general, getting more people to use your API is more important than the occasional duplicate comment from users who haven't read the documentation.

Security and Request Rate Limiting

Users interacting with your UI are limited by their typing speed. If a flow is expensive for your backend, a malicious or careless user will be able to run that flow no faster than the speed of clicks. The situation is different with APIs. All operations exposed via APIs can be called at the speed of code.

Be careful with APIs that do a lot of work in a single request. When I worked at Zendesk, we had an API that sent notifications to all users of a particular app. One clever third-party developer5 exploited this to create an in-app chat system: every message sent a notification to all other users in the account. When accounts had a large enough number of active users, this hack consistently killed the apps' backend server.

We didn't anticipate that anyone would build a chat app on top of this API. But once it was publicly available, people could do whatever they wanted with it. I've dealt with many incidents where the root cause was some client integration doing stupid things like:

Creating and deleting the same entries hundreds of times a minute without any benefit
Infinite polling of a large endpoint /index without pauses
Import or export multiple data without stopping in case of errors

Rate limits should be imposed on API requests, and the more expensive the operations, the stricter the limits should be. It is also wise to provide the ability to temporarily disable the API for specific clients, to relieve the load on the backend system in cases of increased stress.

Add rate limit metadata to API responses. Headers X-Limit-Remaining both Retry-After give clients the information they need to use the API respectfully and allow them to enforce rate limits if needed.

Pagination

Almost every API needs to handle a large list of records. Sometimes this list is extremely long (for example, /tickets Zendesk's API can contain millions of tickets). How can these records be transferred?

A naive solution would SELECT * FROM tickets WHERE... clog up all available memory (if the data is not in a database, this would happen in the application layer where you would try to serialize a list with a million elements). We simply cannot pass all tickets in one request. Pagination is required .

The simplest way to implement pagination is to use pages (or, more generally, "offsets"). When we access , /ticketswe pass the first ten tickets to the account. To get more, we access , /tickets?page=2 or /tickets?offset=20. This is easy to implement because the server can simply append , to the end of the database query OFFSET 20 LIMIT 10. But it doesn't scale well with very large numbers of records. Relational databases have to calculate the offset each time, so each page passed will be slightly slower than the previous one. By the time the offset gets into the hundreds of thousands, this becomes a real problem.

The correct solution is "cursor-based pagination". Instead of passing offset=20 to get the second page, we take the last ticket on the first page (say, with ID 32) and pass cursor=32. The API then returns the next ten tickets, starting with ticket number 32 . The query does not use OFFSET, it is WHERE id > cursor ORDER BY id LIMIT 10. This query is equally fast whether you are at the beginning of the list or hundreds of thousands of tickets later, because the database can instantly find the (indexed) position of the cursor ticket instead of calculating the entire offset.

For databases that are likely to become large, you should always use cursor-based pagination. This is a harder concept for consumers to understand, but when scaling issues start to arise, you will likely be forced to switch to cursor-based pagination, and the cost of making such a change is often very high. However, for other cases, page-based or offset-based pagination is perfectly acceptable.

It's usually a good idea to add a field to API responses with lists next_page. This saves consumers from having to figure out the next page number or cursor themselves.

Optional Fields and GraphQL
If some parts of the API response are expensive to process, make them optional. For example, if the backend must make an API call to get the user's subscription status, you can make the endpoint /users/:id not return the subscription status unless the request passes a parameter include_subscription. In general, you can implement an array parameter includes with all optional fields. This is often used for related records (for example, you can pass a includes: [posts] to the user's request to get the user's posts in the response).

This is one of the principles behind GraphQL , an API style where instead of calling different endpoints for each operation, we create a single request with all the necessary data, and the backend handles it for us 6 .

I don't particularly like GraphQL for three reasons. First, it's completely opaque to non-engineers (and many engineers). Once you learn it, it's a common tool, but the barrier to entry is much higher than GET /users/1. Second, I don't like giving users the freedom to create arbitrary queries. It makes caching more difficult and increases the number of edge cases you have to account for. Third, in my experience, implementing the backend requires a lot more setup than a standard REST API.

I don't have a lot of negativity towards GraphQL. I've been working with it in various contexts for about half a year, so I'm by no means an expert. I'm sure it provides enough flexibility in some cases to make the cost worth it. But for now, I'd only use it when absolutely necessary.

Internal APIs

Everything I've said so far applies to public APIs. What about internal APIs that are used only by colleagues within the company? Some of the assumptions I've made don't apply to internal APIs. For example, their consumers are usually professional software developers. They're also easy to break because (a) there are often orders of magnitude fewer users, and (b) you can release new code to all of those users. You can even add an authentication form if you want.

However, internal APIs can still be sources of incidents, and they must be idempotent for key operations.

Let's sum it up

APIs are hard to develop because they are not flexible, but they must be easy to learn.
The primary responsibility of API maintainers is NOT TO BREAK USER SPACE. Never make breaking changes to public APIs.
API versioning allows for changes, but it creates serious barriers to implementation and adoption.
If your product is valuable enough, the quality of the API doesn't really matter, people will still use it.
However, if your product is poorly designed, then no matter how carefully you design your API, it will likely still be bad.
Your API should support simple API keys for authentication because many users will not be professional developers.
Requests that perform actions (and especially critical actions like payments) should include some kind of idempotency key to secure retries.
Your API will always be a source of incidents. Implement rate limits and a kill switch.
Use pagination with cursors for datasets that have the potential to become very large.
Make expensive fields optional and disabled by default, but GraphQL is overkill (in my opinion).
With internal APIs the situation is a bit different (because the consumers are very different). What I didn't cover? I didn't write much about REST vs. SOAP or JSON vs. XML because I don't think it's that important. I like REST and JSON, but I can't say that nothing else is worth using. I also didn't talk about OpenAPI Schema - it's a useful tool, but I think it's perfectly fine to write API documentation in Markdown if you want.

Don't put off until tomorrow what you can do today

Elliot Brenya sarfo — Sun, 31 Aug 2025 04:05:56 +0000

Don't put off until tomorrow what you can do today. This idea has become one of the key ones for me in developing and documenting applications. "Why?" you may ask.

It's very simple. Tell yourself: "I'll fix this later, and I'll rewrite this later. But this can wait for now. And I'll think about the file system later"? Well, this "later" may never come. And your project will turn into garbage. And even if you remember that it's time to move something somewhere, instead of two files you will have 100 or more. And you will no longer remember what is responsible for what and where it is. As a result, instead of one hour, you will spend a day or more on refactoring, which could and should have been avoided.

In general, the key thing is not to rush to write code right away, but to think everything through first. The structure, architecture, all these little features and so on. At least in general terms. Otherwise, your project will very soon bring you pain, and you will spend time on something completely different from what you would like.

But often laziness, deadlines and other factors prevent this from being done. And here I have no clear recipe for how to treat it. You see, I myself, due to my experience, sometimes stepped on the same rake. But the awareness and understanding did not come to me right away.

Sometimes I saw projects where a simple refactoring of styles took several hours, because all the css was written in one file of 3000 lines. There, identical classes were repeated, and sometimes it was unclear where I broke it, having fixed it in one place. This happened precisely because those who did the code initially did not think about it at all.

Refactoring is an expensive thing in itself. Sometimes in teams and during development, time is always tight. Therefore, even a week or two for refactoring is very cool. And a month is just a dream! That is why it is necessary and important to build the basic tree of project development correctly from the very beginning.

Another problem is that even if we understand in words what we shouldn't do and what we shouldn't, we then go and write code ourselves and don't follow these rules. It's like with advice from good people. They seem to be right, and I agree with them. But then I go and still do it in such a way that it turns out not to be what they advised. And why? Because it's not enough to know, you also need to feel it and understand it internally. And this requires both time and suitable situations. That is, until you pick up all these rakes yourself, you won't be able to realize this - no matter what others tell you and no matter how wise they are.

Sometimes I look at my code that I wrote a year, two, three years ago and think: oh, did I really write that? Well, that's not right! It's all a journey, an evolution.

Just leave yourself time for reflection, analysis and observation. Or even contemplation. It can sometimes lead you to the right path.

But the downside of our frontend — or even a curse — is that the same task can often be solved in different ways. And sometimes there are many of these ways! And at first, some developers have all of them in their heads and it’s hard to figure out what to choose. Of course, I’m exaggerating to emphasize the artistic point. Other languages also have several solutions to a particular problem.

The key reason why we get into a trap is that each specific task on the frontend is not difficult. But there are many of them. The interface comes first, there are many inputs and outputs, and they all have to coexist and work correctly. And when all these layers start to come together, you get a huge layered pie, where the layers can also penetrate each other, and you can’t really figure them out. And if different people wrote it, then no one remembers why Vasya decided not to put this data in the store, no one remembers who wrote this module and how it works. And eventually there comes a point when it’s easier to write it again, because nothing can save you here. And this is an endless cycle of reincarnations, which development revolves around.

And it will spin. You can just make everything a little softer and better.

It is not always worth bringing some heavy stuff into a project if it is as simple as two kopecks. So let it remain simple. But the opposite is also true: it is not always possible to get by with simple implementations, without ts, classes or external services.

In general, I would like to summarize

Before you start coding your app or write that documentation, figure out: what do you need and what do you want to do? What tools will you need for this? What tasks will your app solve? What will potentially be added to it? But don't think 100 steps ahead. Look at 1-2.

If the stack is defined, then define the tools, libraries, and architecture.

After you've written the first iteration with the main page and anything else that already works, do a little revision of what you have. You might notice that somewhere the loading is not working optimally, then you can add some tool. Or something duplicates the same functions.

Repeat the revision process periodically. At least once a month. Set aside time for this. Otherwise, you may encounter problems that, at first glance, should not have arisen. And this will allow you to maintain the code so that it does not become legacy. Of course, if you did not initially choose outdated tools for work.

Connect to Multiple Linux Servers via SSH Without Entering Password: Step-by-Step Guide

Elliot Brenya sarfo — Sun, 31 Aug 2025 03:06:23 +0000

Constantly entering passwords when connecting via SSH irritate me a lot. I used to have several local machines, and every time I type the keys, remembering what the password is... But there is a simple solution now which is SSH keys.

You set it up once, and then everything goes like clockwork. Like one password but for servers.

In this article, I will tell you how to do it step by step, especially if you are new to Linux or SSH.

First, a few words about what SSH is.

SSH (Secure Shell) is a protocol for secure remote access to a server. It encrypts all data so that no one can eavesdrop on your password or commands. Usually, you connect with a command like ssh user@ip-аddress, and the server asks for a password. But with keys, no password is needed authentication happens automatically through cryptography.

Key point

You don't have to create a separate key for each server. One good key can be "distributed" to all the machines you want to connect to. This saves time and effort. I've been doing this for a long time, and it really simplifies life, especially if you have a cluster of servers or virtual machines on your home network.

Setup steps

Step 1: Generate SSH key (done once)

First, you need to create a pair of keys: private and public. It's like a lock and a key - the private key stays with you, and the public "lock" is placed on the servers.

Open a terminal (on Windows, this could be PowerShellor Git Bashif you have Git installed). Enter the command:

ssh-keygen -t ed25519 -C "your_email@example.com"
Let's take a look at what's going on here:

ssh-keygen : This is a key generation utility. It is part of the standard OpenSSH suite, which is usually already installed on most systems.

-t ed25519 : Option for key type. Ed25519 is a modern algorithm, it is fast, secure and compact.

-C " your_email@example.com " : This is a comment that is added to the key. Not required, but useful for identification - for example, if you have several keys. Replace with your real email.

When you run the command, it will ask where to save the files. By default, it is C:\Users<your_name>.ssh\id_ed25519(on Windows) or ~/.ssh/id_ed25519(on Linux/Mac). If it asks you to overwrite the existing key, do not agree unless you want to lose the old one.

Then it will ask you to enter passphrase(password for the key). This is optional, but I recommend setting it - this is additional protection. If there is no passphrase, then the connection will be completely automatic, but if someone steals your private key, they will get access to everything. With passphrasethe key "locked" until you enter the password, but for automation (for example, in scripts) this may be inconvenient.

As a result, two files will be created:

id_ed25519 — private key. This is your "secret key", never copy it to other machines!

id_ed25519.pub is a public key. It can be distributed left and right.

If you have Windows, check the folder .sshin your profile. If it is not there, it will be created automatically.

Step 2: Copy the public key to the servers

Now you need to "install" the public key on each server. There is a convenient command for this ssh-copy-id.

For each server, run:

ssh-copy-id -i "C:\Users<your_name>.ssh\id_ed25519.pub" user@IP-address
Let me explain the parameters:

-i "path_to_public_key": Specifies which key to copy. Replace with the actual path.

user@IP-address: Here user is the username on the server (for example, administrator or root), and IP address is the server address, like 192.168.98.98.

The first time you run it, it will ask for a password (yes, for the last time!). It will connect via SSH, add your public key to a file ~/.ssh/authorized_keyson the server, and exit. Repeat this for all servers.

If ssh-copy-idit doesn't work (on older systems), you can do it manually: copy the contents id_ed25519.pub(open in notepad, for example), connect to the server via SSH with a password, create a file ~/.ssh/authorized_keys(if not), and paste the key string at the end of the file. Don't forget to set the rights: chmod 600 ~/.ssh/authorized_keys.

Step 3: (Optional) Customize the config file for convenience

To avoid typing long commands like ssh admin@192.168.98.98, create a file ~/.ssh/config(on Windows C:\Users<ваше_имя>.ssh\config). It's like an address book for SSH.

Open the file in an editor (notepad will do) and add blocks like:

Host server1
    HostName 192.168.98.98
    User admin
    IdentityFile ~/.ssh/id_ed25519

Host server2
    HostName 192.168.98.214
    User administrator
    IdentityFile ~/.ssh/id_ed25519

Host server1: This is the alias how you will call the server.

HostName: Real IP or domain.

User: Default username.

IdentityFile: Path to the private key.

Save the file. Now connecting is easy ssh server1. Cool, right?

Step 4: Checking the connection

Now try: ssh server1.

If everything is OK, it will connect without a password. If it asks passphrase, enter it (if you set one).

How it works under the hood

Let's figure out why this works, so there is no magic. SSH keys are based on asymmetric cryptography ( public-key cryptography ). When generated, a pair is created:

Private Key: Stored only by you, used to "sign" the connection request.

Public key: Open, located on servers in authorized_keys.

When you connect, the client (your computer) sends a request: "Hey, server, I have a private key that matches this public one." The server generates a random challenge, the client "signs" it with the private key, the server checks the signature with the public key. If it matches, welcome!

The public key is not a secret because it cannot be used to "hack" the private key. But the private key is, yes, your main asset.

Conclusion

That's it! Now you can connect to a bunch of servers without passwords.

ChatGPT vs. My System Cleanup Script: Who's Winning?

Elliot Brenya sarfo — Sun, 31 Aug 2025 02:50:04 +0000

Some time ago, while studying bash scripts, I tried to delve deeper into the topic and looked for more practice by solving any, even the smallest, tasks. One of these was a script that deletes temporary files, old dumps, folders node_modulesfrom long-forgotten projects. I found it the other day completely by accident. I tested it on a virtual machine, the script works, but is terribly hacky and visually unpleasant.

What idea did I have? To check if ChatGPT can do the same (and how well) as I did, but more competently. The result was quite instructive: the AI did a great job with the architecture, but really tried to ruin the system with a couple of lines. Below I will tell you how it was.

The task is simple, you need to automatically find and delete unnecessary files according to certain rules. My old script was a monolith: with a bunch of repeating findand rm -rfawkward attempts to handle errors. Please do not judge me too much in advance, I was just learning Bash and its capabilities.

The main problems of my creation

Commands rm -rf with variable concatenation are a game of Russian roulette (concatenation is the combination of two or more strings into one).

Any gap in the path and the script will silently "fly" past the target or delete the wrong thing.

To change the rules, you need to go directly into the code there are no proper settings at the beginning.

The script did not log what exactly it deleted (or did not delete?). It worked in silence, which is always alarming.

I sent ChatGPT the TOR: "Write a secure and customizable script to search/delete temporary files, caches, and old logs. Add a whitelist of folders that cannot be accessed. Add logging."

Step-by-step code analysis before and after

I'll start by demonstrating that very "cheat" script, for which I am extremely ashamed. It was really hard to share this.
My version (comments were added by me before writing the article for better understanding)

#!/bin/bash
# If $DIR contains a space, the command will split into two
DIRS="/tmp ~/cache ~/projects/*/node_modules"
# Remove everything at once
for dir in $DIRS; do
    echo "Removing $dir"
    rm -rf "$dir"  # Quotes are here, but the for loop breaks them anyway, right?
done
# Find and delete all .log and .tmp files older than 30 days
find ~/ -name "*.log" -mtime +30 -exec rm {} \; 2>/dev/null
find ~/ -name "*.tmp" -mtime +30 -exec rm {} \; 2>/dev/null
echo "Cleanup done!"

This code is a product of colossal laziness (after all, he could have "read the Internet" and done better…). It deletes node_modulesrecursively, without looking, silently ignores any errors ( 2>/dev/null), which can hide existing rights issues.

Python version from ChatGPT

I want to point out in advance that the choice of Python is not accidental, but a conscious choice. I wanted to emphasize the difference in approaches between a "script on the knee" and a well-thought-out, reliable tool.

ChatGPT, tasked with making quality and secure software, intuitively understands that Bash is not the right tool for the job. The main aspect of any script is security, and Bash has no built-in mechanisms for secure file deletion. Security literally depends on proper escaping and the hope that no variable is accidentally empty.

I gave the prompt: "Write a safe and configurable system cleanup script. It should remove old files, have a blocklist for dangerous directories (like /, /home, etc.), and log its actions to a file. Avoid using shell commands directly."

Here's what the AI suggested (my comments and subsequent edits were added)

# cleanup_agent.py
import os
import logging
import time
from pathlib import Path
# === CONFIGURATION ===
TARGETS = [
    {
        "path": os.path.expanduser("~/Downloads"),
        "patterns": ["*.tmp", "*.temp", "*.log"],
        "max_age_days": 7
    },
    {
        "path": os.path.expanduser("~/.cache"),
        "patterns": ["*"],
        "max_age_days": 30
    }
]
# Directories that must never be touched (!)
BLOCKLIST = {
    os.path.expanduser("/"),
    os.path.expanduser("~"),
    os.path.expanduser("~/.ssh"),
}
# Logging setup
logging.basicConfig(
    filename=os.path.expanduser('~/cleanup_agent.log'),
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)
def safe_remove(target: Path):
    """Safely remove a file or empty folder with logging"""
    try:
        if target.is_file():
            target.unlink()  # Remove file
            logging.info(f"Removed file: {target}")
        elif target.is_dir():
            target.rmdir()  # Remove empty folder only
            logging.info(f"Removed empty folder: {target}")
    except OSError as e:
        # Log error but don't crash
        logging.error(f"Failed to remove {target}: {e}")
def cleanup_directory(config: dict):
    """Clean a directory based on config"""
    base_dir = Path(config["path"])
    if not base_dir.exists():
        logging.warning(f"Directory not found: {base_dir}")
        return
# Check if directory is in blocklist
    if any(blocked in base_dir.parents for blocked in BLOCKLIST):
        logging.error(f"Attempted cleanup of protected directory: {base_dir}. Aborting.")
        return
current_time = time.time()
    for pattern in config["patterns"]:
        for target in base_dir.rglob(pattern):  # Recursive search
            if not target.exists():
                continue
# Check file/folder age
            age_days = (current_time - target.stat().st_mtime) / (60 * 60 * 24)
            if age_days > config["max_age_days"]:
                safe_remove(target)
if __name__ == "__main__":
    logging.info("=== Cleanup started ===")
    for job in TARGETS:
        cleanup_directory(job)
    logging.info("=== Cleanup finished ===\n")

Comparative analysis

Where ChatGPT was right
Made the script as secure as possible. Eliminated such rm -rfdirect calls using Python's built-in methods ( unlink, rmdir). A BLOCKLIST, which completely prohibits any attempts to get into /or , appeared $HOME.

Added customizability. Instead of hardcode - a good config in the form of a list of dictionaries TARGETS. Need to clean another folder or change the "age"? Just edit the list without changing the code. In my opinion, the right and competent solution.

The script now maintains a full log file. Now you can see not only what was deleted, but also why something is going wrong.
Use pathlib.Pathinstead of string concatenation, which is more correct work with paths. It automatically handles different OS and escapes special characters.

Where ChatGPT was not quite right (in my opinion, please correct me if I'm wrong)

A bit dangerous recursive search. Initially AI used base_dir.rglob('')for pattern ""in ~/.cache. This literally means: "go recursively through EVERYTHING in the cache and check the age of EVERY file". For a cache directory, where there are a huge number of small files, this could easily lead to incredibly long and useless work. I would add a condition for a minimum age for such an aggressive cleaning.

Imitation of security. The function safe_removetries to delete the folder only if it is empty. This is safe, but completely useless for node_modules. For "non-empty" directories, the script will simply ignore them. It would be worth explicitly specifying this in the logging.

Not the most practical templates. The template ""is ~/.cachetoo wide. It would be more correct: ['.bin', 'cache/', 'thumbnails/']etc.

What conclusion can be drawn: ChatGPT made a low-quality and slightly dangerous bash script into a nearly production utility with config and logs. But blind confidence in recursive traversal of "everything and everyone" could easily hang the system. AI structures and secures the code perfectly, but it seems to lack a specific understanding of "what exactly should I clean?" As an auxiliary tool for generation, it is an indispensable thing, but you need to know the material well and very carefully monitor the generated code in order to avoid dangerous consequences.

Example of use

As usual, the instructions for the script are in the article (maybe someone will need it?)

Save the code to a file cleanup_agent.py.
We edit the config TARGETSfor the required tasks. It is necessary to clean Downloadsonce a week - please. It is necessary to clean Projectsfrom pycache- we add a rule.
Let's launch it and look at the logs.

# Make the script executable
chmod +x cleanup_agent.py
# Run the script
python3 cleanup_agent.py

Check the log output

tail -f ~/cleanup_agent.log
The output in the log will be something like this:
2025-08-19 11:05:32,123 - INFO - === Cleanup started ===
2025-08-19 11:05:32,456 - INFO - Removed file: /home/user/Downloads/old_report.tmp
2025-08-19 11:05:33,001 - ERROR - Failed to remove /home/user/.cache/some_file: [Errno 13] Permission denied
2025-08-19 11:05:33,002 - INFO - === Cleanup finished ===

Tip: run with sudo only if you really need to touch protected paths. Otherwise leave permission errors as is.

Run n8n locally

Elliot Brenya sarfo — Sun, 24 Aug 2025 05:37:37 +0000

Elliot Brenya sarfo

Aug 24 '25

Running n8n Locally Without Regrets.

#programming #webdev #javascript #tutorial

Comments

7 min read

Sync Obsidian Across Your Devices For Free, With GitHub And A Bit Of Nerve.

Elliot Brenya sarfo — Sun, 24 Aug 2025 04:27:29 +0000

I like tools that stay on disk. I like Markdown that opens in any editor. Obsidian does both. The catch is sync. The official option is paid. I wanted control and a zero bill. Git and GitHub gave me both. The setup takes a few minutes. After that, it feels like magic you can explain.

What you will use

A private GitHub repository to hold your vault.
Git on your desktop.
Obsidian with the Obsidian Git plugin. On iPhone or iPad, iSH as a tiny Linux shell that can run Git.
That is the whole cast.

Step 1. Create the home for your notes

Open GitHub. Create a new repository. Name it something you will not hate later. Make it private. This is your vault’s remote. This is where history lives.

Step 2. Teach your machine Git

Install Git if you do not have it. On Windows, grab Git for Windows. On macOS, use the Git installer or Homebrew. On Linux, use your package manager. Then confirm the version. You want a recent build.

git --version

Step 3. Clone the empty home

Pick the folder where your vault will live. Clone the new repository into it. If Git asks for a password, use a Personal Access Token. GitHub moved away from passwords for Git operations. The token is your key. Create one in Developer settings. Give it access to the repo. Copy it once. Paste it when Git prompts.

cd /path/to/where/you/want/your/vault
git clone https://github.com/your-user/your-vault.git

Step 4. Or set up SSH and forget about prompts

If you prefer no prompts at all, create an SSH key, add it to your account, and clone with the SSH URL. It takes a minute and pays off every day.

ssh-keygen -t ed25519 -C "you@example.com"
cat ~/.ssh/id_ed25519.pub
# Add that to GitHub: Settings → SSH and GPG keys
git clone git@github.com:your-user/your-vault.git

Step 5. Point Obsidian at the folder you just cloned

Open Obsidian. Choose “Open folder as vault.” Pick the folder you cloned. Your vault is now under Git. Install the community plugin called “Obsidian Git.” Enable it. Set Auto commit to a small interval. Enable Pull on startup. These two switches remove most of the daily friction.

Step 6. Move your notes in, make the first commit

If you had notes elsewhere, move them into this folder. Watch the status bar. The plugin will notice changes, stage them, and commit them. If it does not push by itself on your setup, use the command palette and run the push command once. The next pull on startup brings everything up to date on other devices.

# from a terminal in your vault
git status
git add .
git commit -m "First commit of my vault"
git push

Step 7. Bring your phone into the circle

On iOS, install Obsidian. Install iSH. iSH gives you a small Linux userland with apk. Open iSH. Install Git. Create a folder called obsidian. Mount your mobile vault folder into that path. Then turn that mount into a Git working tree by cloning into it. Obsidian will see the files appear.

apk add git
mkdir obsidian
mount -t ios . obsidian
cd obsidian
git clone https://github.com/your-user/your-vault.git .

Open Obsidian on the phone. In Settings, install Obsidian Git there too. Turn on auto commit. Turn on Pull on startup. The phone and your desktop now meet in the middle.

What I learned while living with it

Keep the repository private. Use a token or SSH. Pull before long edits. Let the plugin do small, frequent commits. If something feels off, drop to a terminal and read git status. The clarity helps. The official plugin docs list the features I rely on every day, including scheduled sync and startup pulls.

Upgrades, changes, safety

If you switch laptops, you do not copy files by hand. You clone the repo and open it as a vault. If you change your plugin settings on one device, that .obsidian state will sync too. If you prefer to keep some UI state local, you can ignore parts of .obsidian with a .gitignore. The Obsidian forum has threads that discuss which files to ignore if you want that split.

When it works, it feels quiet. You write a note on the Elon Musk jokes. You sit down at night and the change is already there. No paid sync. No mystery background process. Just Git doing what Git does. You own the flow end to end. That is the point.

Running n8n Locally Without Regrets.

Elliot Brenya sarfo — Sun, 24 Aug 2025 04:02:12 +0000

I like tools that give me control. I like seeing the logs roll in my own terminal. I like knowing where the database file lives. n8n fits that mood. It connects your apps, moves your data, and runs on your own machine. When something breaks, you can still touch the files, read the config, and fix it. That is the point of a local install.

There are two roads. Docker, where you get a neat, sealed box that behaves the same on every machine. Or Node and npm, where you install n8n like any other CLI and own the runtime. You can switch between them later, but it helps to pick the one that matches how you work today.

First, a few truths. The editor listens on port 5678 by default. If something else is already there, you will hit a connection error. You can change n8n’s port with an environment variable and keep moving. That small change saves an hour of second guessing your setup when a VPN client or a forgotten dev server is the real problem. Community threads say the same thing. When 5678 is busy, switch the port and carry on.

Now the version question. n8n moves fast. New minor versions land most weeks. The docs call the stable channel latest and a faster, beta-ish channel next. Right now, the npm path expects Node in the 20.19 to 24.x range, inclusive. If you stay in that lane, you avoid the “works on my laptop” ghost hunt. The page that says this also shows the current latest and next numbers, which helps when you pin versions.

Docker path

Docker is calm once it is running. You install Docker Desktop on macOS or Windows, or the engine on Linux, then you start a container with a persistent volume. That volume holds your world, the SQLite file by default, the encryption key, the logs, the bits n8n needs to remember who it is. The official command in the docs does a lot for you in one go, including the timezone and safer file permissions. It also enables task runners, which n8n now recommends. Run this as written, swap the timezone for yours, and you get a clean, predictable start.

docker volume create n8n_data

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Europe/Berlin" \
  -e TZ="Europe/Berlin" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Open the browser, go to http://localhost:5678, create the owner account, and you are home. That’s the easy part. The next choice is your data store. The default is SQLite in that mounted directory. It is fine for a personal notebook of automations. When you outgrow it, n8n speaks PostgreSQL through environment variables. Even then, you should still keep the volume. The encryption key and other instance data live there, and you want them to survive a container restart. The docs say this outright.

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Europe/Berlin" \
  -e TZ="Europe/Berlin" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -e DB_TYPE=postgresdb \
  -e DB_POSTGRESDB_DATABASE=n8n \
  -e DB_POSTGRESDB_HOST=localhost \
  -e DB_POSTGRESDB_PORT=5432 \
  -e DB_POSTGRESDB_USER=n8n \
  -e DB_POSTGRESDB_SCHEMA=public \
  -e DB_POSTGRESDB_PASSWORD=supersecret \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

When you need a first-class HTTPS endpoint and a real hostname, reach for Docker Compose with Traefik. You get automatic certificates, a stable URL, and a reverse proxy that routes traffic to the editor. The official compose file wires this up in a way you can read in one pass. It binds the editor to 127.0.0.1 and lets Traefik publish 80 and 443. It also sets N8N_HOST, N8N_PORT, N8N_PROTOCOL, WEBHOOK_URL, and the timezone. Paste their compose file, fill the .env, and bring it up. Yes, it is production-leaning, even on a small VM.

# .env
DOMAIN_NAME=example.com
SUBDOMAIN=n8n
GENERIC_TIMEZONE=Europe/Berlin
SSL_EMAIL=user@example.com

# compose.yaml
services:
  traefik:
    image: "traefik"
    restart: always
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.mytlschallenge.acme.tlschallenge=true"
      - "--certificatesresolvers.mytlschallenge.acme.email=${SSL_EMAIL}"
      - "--certificatesresolvers.mytlschallenge.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - traefik_data:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro

  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "127.0.0.1:5678:5678"
    labels:
      - traefik.enable=true
      - traefik.http.routers.n8n.rule=Host(`${SUBDOMAIN}.${DOMAIN_NAME}`)
      - traefik.http.routers.n8n.tls=true
      - traefik.http.routers.n8n.entrypoints=web,websecure
      - traefik.http.routers.n8n.tls.certresolver=mytlschallenge
      - traefik.http.middlewares.n8n.headers.SSLRedirect=true
      - traefik.http.middlewares.n8n.headers.STSSeconds=315360000
      - traefik.http.middlewares.n8n.headers.browserXSSFilter=true
      - traefik.http.middlewares.n8n.headers.contentTypeNosniff=true
      - traefik.http.middlewares.n8n.headers.forceSTSHeader=true
      - traefik.http.middlewares.n8n.headers.SSLHost=${DOMAIN_NAME}
      - traefik.http.middlewares.n8n.headers.STSIncludeSubdomains=true
      - traefik.http.middlewares.n8n.headers.STSPreload=true
      - traefik.http.routers.n8n.middlewares=n8n@docker
    environment:
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - N8N_RUNNERS_ENABLED=true
      - NODE_ENV=production
      - WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - TZ=${GENERIC_TIMEZONE}
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files

volumes:
  n8n_data:
  traefik_data:

Bring it up, visit https://n8n.example.com, and you have a tidy HTTPS setup without touching OpenSSL by hand. That recipe comes straight from the docs, and it is a strong default for a home lab or a small team server.

npm path

You might not want Docker. Maybe you already live in Node. Maybe you need n8n on a workstation where containers are not allowed. npm is fine. You install once, then you start the app like any other CLI. The docs are clear on the Node range. Stay between 20.19 and 24.x and you are safe. You can try n8n with npx if you want a quick smoke test. When you are ready, install globally and start.

npx n8n

npm install -g n8n
n8n start

There is a tunnel flag for webhook testing. It gives you a public URL that forwards to your local editor. It is great for GitHub, Stripe, or any service that needs to call back into your machine during development. Use it for dev only. The docs warn against using it in production, and they are right.

n8n start --tunnel

If you are on Windows, Docker can feel touchy with file sharing and virtualization switches. Community writeups show a path that works, including the Hyper-V enablement and the right sharing settings. If you get odd permission errors or volumes that refuse to mount, check those flags first. It saves a day.

Upgrades and pinning

You can update a Docker install by pulling a new image, then restarting the container. You can pin a version by tag. You can do the same on npm by installing a specific version or the next channel. The docs list the current latest and next on the install pages. Read them before you bump. A small warning helps, treat next like a beta. Stable is latest.

docker pull docker.n8n.io/n8nio/n8n
docker pull docker.n8n.io/n8nio/n8n:1.107.4
docker pull docker.n8n.io/n8nio/n8n:next

npm update -g n8n
npm install -g n8n@1.107.4
npm install -g n8n@next

First workflow, proof you are alive

The fastest way to prove your instance works is a tiny workflow that hits a public API, transforms the result, and logs it. In the editor, add a Manual Trigger. Add an HTTP Request to https://jsonplaceholder.typicode.com/todos/1. Connect them, run once, and watch the data flow. You will see the response as JSON, you will see the execution in the list, you will feel the system breathe. If you prefer a schedule, drop in a Schedule Trigger and set it to every hour. The timezone you set earlier will keep it sane. That setting exists because time in workflows is tricky, and n8n handles it with a clean variable for scheduling, plus the TZ for the system clock. The install docs cover both.

Small security moves that pay off

Turn on authentication if you expose the editor on a network you do not control. Put n8n behind HTTPS. If you run Compose with Traefik, you get TLS out of the box. Keep your .n8n directory safe, it holds your encryption key. Keep backups of that volume. If you lose that key, you lose access to encrypted credentials. The Docker page explains why persisting that directory matters even with PostgreSQL. That sentence has saved more than one weekend.

When things feel wrong

Port busy, change it. Set N8N_PORT and move on. Node too old, upgrade to a supported range. If an npm upgrade stalls with dependency noise, check the docs for reverting a migration and step back one version. The npm page shows the db:revert flow for multi-step rollbacks. You can recover cleanly if you read and respect the release notes.

When to choose which road

If you want a clean slate and easy upgrades, Docker is the default. If you are building custom nodes and like local control of Node, npm feels natural. Both are first-class in the docs. Both will get you to the editor screen at http://localhost:5678 in a few minutes. The choice is not forever. You can migrate your workflows later by exporting and importing, and you can keep the same PostgreSQL database if you standardize on it early.

You came here to run n8n locally, not to fight your tools. Start with Docker if you are unsure. Start with npm if your machine is already a good Node citizen. Set a timezone, pick a port, keep the .n8n volume safe. Build one workflow that makes you smile. When you are ready to share it with the world, move to Compose and Traefik and give it a real URL.

If you love my write up let's connect on twitter or Linkedin

50+ Remote Job Websites You Need to Know About 🌍💼

Elliot Brenya sarfo — Wed, 22 Jan 2025 18:48:24 +0000

I've compiled an extensive list of job boards specifically focused on remote positions. Whether you're a developer, designer, or working in other tech roles, these platforms will help you find your next remote gig.

Why Remote Work? 🤔

Remote work has become more than just a trend—it's the future of work. It offers:

🏠 Better work-life balance
🌎 Freedom to work from anywhere
💰 Access to global opportunities
⏰ Flexible schedules
💪 Increased productivity

Job boards

Real Work From Anywhere - A curated platform dedicated to 100% remote positions. They verify all job listings to ensure they are truly location-independent, making it easier to find genuine remote opportunities without geographic restrictions.
4 Day Week - Specializes in tech jobs with companies offering compressed work weeks. Perfect for developers seeking better work-life balance with companies that prioritize employee wellbeing.
Authentic Jobs - A long-standing job board focused on design, development, and creative tech roles. Known for high-quality listings from established companies and startups.
Built In - A comprehensive tech career platform featuring jobs from innovative companies. Offers detailed company profiles, salary information, and culture insights along with job listings.
ClojureJobboard.com - The go-to platform for Clojure developers. Features specialized roles for functional programming enthusiasts with remote options.
Crypto Jobs - Exclusively focused on blockchain and cryptocurrency positions. Perfect for developers interested in Web3 technologies and decentralized systems.
Crypto Jobs List - The largest Web3 job board with positions in blockchain, DeFi, and NFT projects. Features both technical and non-technical roles in the crypto space.
Cryptocurrency Jobs - High-quality crypto job board with positions from established blockchain companies. Includes detailed salary ranges and comprehensive job descriptions.
CyberJobHunt.in - Specialized in cybersecurity positions across all experience levels. Features roles in security engineering, penetration testing, and security analysis.
Daily Remote - A modern job board with an extensive collection of remote positions. Offers powerful filtering tools and daily updates of new opportunities.
Diversify Tech - Focuses on inclusive tech opportunities. Companies posting here actively support diversity and inclusion initiatives, making it ideal for underrepresented groups in tech.
Dribbble Jobs - Premier platform for design professionals. Features UI/UX, graphic design, and creative tech roles from top companies.
Drupal Jobs - The official job board for Drupal developers. Perfect for finding roles in agencies and organizations using Drupal.
freelancermap - Popular in German-speaking regions but open globally. Focuses on IT consulting and freelance projects with good rates.
Golangprojects - Specialized in Go programming language positions. Ideal for Golang developers seeking remote opportunities.
Guru - A platform offering a wide range of freelance and contract jobs across various categories, including tech, design, and more.
HackerX - A platform that connects developers with top companies. Offers a unique approach to job searching with a focus on coding skills.
Hasjob – Location filter -> "Anywhere/Remote". A job board featuring a variety of tech and non-tech roles with remote options.
HigherEdJobs - Specializes in higher education jobs, including remote opportunities in academia and administration.
HN hiring – Filter REMOTE. A job board featuring tech and startup jobs, including remote positions.
JOBBOX.io – Filter -> Remote only. A platform offering a curated selection of tech jobs, including remote opportunities.
JobsCollider - * Tens of thousands of remote jobs from over 10,000 companies and startups worldwide. *
Jobspresso * High-quality remote positions that are open and legitimate *
JustRemote - A remote job board featuring a wide range of positions, including tech, marketing, and customer support.
Larajobs – The artisan employment connection. Specializes in Laravel and PHP jobs, including remote opportunities.
No Fluff Jobs – Filter -> "remote". A job board featuring tech jobs without the fluff, including remote positions.
NODESK - A remote job board featuring a curated selection of tech and startup jobs.
Power to Fly - A platform focused on women in tech, offering remote job opportunities and resources for career development.
Remote AI Jobs - Remote AI jobs in Machine Learning, Engineering, Data Science, Research, etc.
Remote Backend Jobs - Find exclusively remote backend jobs aggregated from the top 22 job boards in the world.
Remote Frontend Jobs - Find exclusively remote frontend jobs aggregated from the top 22 job boards in the world.
PyJobs.com - Jobs for Python developers, including remote opportunities.
Remote Game Jobs - Find remote work and talent in the game industry.
remote-es/remotes - Repository listing companies which offer full-time remote jobs with Spanish contracts.
thatmlopsguy/remote-pt - Repository listing companies which offer full-time remote jobs with Portuguese contracts.
remote-jobs - A list of semi to fully remote-friendly companies in tech.
Remotees - A remote job board featuring a wide range of positions, including tech, marketing, and customer support.
Remote.co Jobs - A platform offering a curated selection of remote jobs, including tech, marketing, and more.
RemoteJobs.lat - Remote jobs for LATAM people.
Remotive Jobs - A remote job board featuring a wide range of positions, including tech, marketing, and customer support.
Remote People - A platform offering a curated selection of remote jobs, including tech, marketing, and more.
Remote Works - Remote jobs in software development.
Ruby On Remote - All ruby remote jobs in one place.
Skip the Drive - A job search platform featuring remote and flexible job opportunities.
Slasify - Remote tech, art/design and marketing opportunities from Asia, global payroll service included.
Stream Native Jobs - Scroll down to Join Us.
SwissDev Jobs - Filter -> "Remote / Work from home".
UI & UX Designer Jobs - Remote jobs for UI, UX & UXR Designers.
Upwork - Find remote jobs in any category.
Virtual Vocations - A job search platform featuring remote and flexible job opportunities.
Vue.js Jobs Find Vue.js jobs all around the world - Click on "Remote" tab.
Web3Jobs - Remote Web3 Jobs.
Wellfound - Startup Jobs. Search by going to Job Type, and selecting "Remote OK".
We Work Remotely - A remote job board featuring a wide range of positions, including tech, marketing, and customer support.
Workana Freelance Job Board in Spanish and Portuguese.
Working Nomads - A remote job board featuring a wide range of positions, including tech, marketing, and customer support.
zuhausejobs.com - Remote Jobs in German-speaking countries (Germany/Austria/Switzerland).
Dataaxy Job board and reverse job board specialized in Data and AI in North America.
Freel Freelancers job board in Canada.
DevOpsJobs DevOps, SRE, Cloud and Platform engineering jobs.

Pro Tips for Remote Job Hunting 🎯

Tailor Your Profile: Each platform has its unique features. Make sure your profile is complete and optimized for each site.
Set Up Alerts: Most of these platforms offer job alerts. Use them to be among the first applicants.
Niche Platforms: Consider using niche job boards specific to your skills (e.g., PyJobs for Python developers).
Global Opportunities: Don't limit yourself geographically unless necessary. Many companies hire globally!
Check Regularly: Remote positions often fill quickly. Make job searching a regular part of your routine.

Ready to Start? 🚀

This list includes platforms for various specialties:

General remote work
Tech-specific roles
Freelance opportunities
Regional job boards
Cryptocurrency and Web3
AI and Machine Learning
Design and UX

Pick the platforms that best match your skills and career goals. Happy job hunting! 🌟

Remember to follow me for more articles about remote work, tech careers, and professional development!

The Best Tech Stacks for AI-Powered Applications in 2025

Elliot Brenya sarfo — Tue, 07 Jan 2025 05:00:56 +0000

As we move into 2025, AI development has evolved beyond experimental projects to production-ready applications. Let's explore the most effective tech stacks for different AI development scenarios, starting with the most modern and popular stack.

1. Modern Full-Stack AI Stack

This stack represents the cutting edge of AI application development in 2025, combining the best tools for a seamless development experience.

Core Components:

Frontend/Backend: Next.js
Database: Neon + Prisma
AI Integration: Together AI
AI Coding assistance: Windsurf + Bolt.ai
Scrapers: Firecrawl
Firmware: Firmware-ci.com
Search: Serper API
Language: TypeScript
Hosting: Vercel
UI: Tailwind CSS + shadcn/ui
Authentication: Clerk
Analytics: Plausible
Observability: Helicone

Why Use Modern Full-Stack AI Stack in 2025?

Rapid Development: Next.js + TypeScript provides a robust foundation
AI-First Design: Built-in AI capabilities with Together AI
Modern UI: Beautiful, responsive interfaces with Tailwind + shadcn
Scalable Data: Neon's serverless Postgres with Prisma's type safety
Production-Ready: Enterprise-grade auth and analytics included

Best For:

AI-Powered SaaS Applications
Modern Web Applications with AI Features
Startups Moving Fast
Projects Requiring Quick Iteration

2. Python AI Stack (PyTorch/TensorFlow, FastAPI, PostgreSQL)

The Python AI stack remains the most versatile and widely-supported option for AI development, especially for data-intensive applications.

Why Use Python AI Stack in 2025?

Extensive ML Libraries: Access to PyTorch and TensorFlow ecosystems
Production-Ready APIs: FastAPI provides high-performance API development
Scalable Data Handling: PostgreSQL with vector extensions for AI data storage
Rich Ecosystem: Vast collection of AI-focused tools and libraries

Best For:

Machine Learning Models
Natural Language Processing
Computer Vision Applications
Predictive Analytics Systems

3. JavaScript AI Stack (TensorFlow.js, Node.js, MongoDB)

For teams looking to build AI-powered web applications with client-side capabilities, the JavaScript stack offers unique advantages.

Why Use JavaScript AI Stack in 2025?

Browser-Based ML: Run models directly in the browser
Real-Time Processing: Excellent for interactive AI features
Full-Stack JavaScript: Unified language across frontend and backend
Rich UI Capabilities: Seamless integration with modern web frameworks

Best For:

Web-Based AI Applications
Real-Time AI Features
Interactive ML Demonstrations
Client-Side AI Processing

4. Enterprise AI Stack (Java Spring Boot, DJL, PostgreSQL)

Enterprise environments require stability, scalability, and robust security features.

Why Use Enterprise AI Stack in 2025?

Production Stability: Battle-tested enterprise-grade components
Strong Type Safety: Reduced runtime errors in production
Excellent Scaling: Built for high-throughput applications
Corporate Integration: Easy integration with existing enterprise systems

Best For:

Large-Scale AI Deployments
Financial Services Applications
Healthcare Systems
Enterprise Data Processing

5. Cloud-Native AI Stack (AWS SageMaker/Google Vertex AI)

Cloud-native stacks offer the advantage of managed services and scalable infrastructure.

Why Use Cloud-Native Stack in 2025?

Managed Infrastructure: Reduced operational overhead
Auto-Scaling: Handles varying workloads efficiently
Integrated Services: Complete ML lifecycle management
Cost Optimization: Pay-as-you-go pricing model

Best For:

Startups Moving Fast
Teams Without DevOps Resources
Scalable AI Services
Quick Prototyping

6. Edge AI Stack (TensorFlow Lite, Flutter, Firebase)

For applications requiring AI processing on mobile or edge devices.

Why Use Edge AI Stack in 2025?

Offline Processing: AI capabilities without constant cloud connection
Battery Efficiency: Optimized for mobile devices
Cross-Platform: Single codebase for multiple platforms
Reduced Latency: Process data closer to the source

Best For:

Mobile AI Applications
IoT Devices
Real-Time Processing
Privacy-Focused Applications

7. MLOps Stack (Kubernetes, MLflow, Kubeflow)

For teams focusing on the operational aspects of AI deployment.

Why Use MLOps Stack in 2025?

Automated Deployment: Streamlined model deployment process
Version Control: Track models and experiments effectively
Monitoring: Comprehensive model performance tracking
Scalability: Handle multiple models in production

Best For:

Large-Scale ML Operations
Model Lifecycle Management
Production AI Systems
Team Collaborations

Choosing the Right Stack

The best stack for your AI application depends on several factors:

Use Case Requirements
- Real-time processing needs
- Data volume and velocity
- Security requirements
- Scalability expectations
Team Expertise
- Existing technical knowledge
- Available learning resources
- Community support
Infrastructure Constraints
- Budget considerations
- Deployment requirements
- Integration needs

Future Trends

As we progress through 2025, watch for these emerging patterns:

Increased focus on edge AI capabilities
Greater emphasis on AI model efficiency
Rising importance of explainable AI
Growing need for AI governance tools

Conclusion

The ideal AI tech stack in 2025 isn't about choosing the newest tools – it's about selecting the right combination that meets your specific needs. Consider your use case, team capabilities, and infrastructure requirements when making your choice.

What tech stack are you planning to use for your AI project? Share your thoughts and experiences in the comments below.

Is AI Making Technical Writers Obsolete?

Elliot Brenya sarfo — Tue, 07 Jan 2025 03:57:14 +0000

A successful technical writer is someone who can transform complex technical information into clear, user-friendly documentation that solves real problems. With the rise of AI tools like ChatGPT and Google Bard, many technical writers are wondering about their future in the industry.

To understand the real impact of AI on technical writing, you need to understand three key things:

What AI can and cannot do in technical writing
How to use AI effectively in your workflow
Where human expertise remains irreplaceable

This article will show you the current state of AI in technical writing and how to position yourself for success in this changing landscape.

Here are the key areas we will be covering:

The Current State of AI in Technical Writing
How AI Tools Actually Work in Documentation
Where Human Writers Excel
How to Adapt and Thrive

The Current State of AI in Technical Writing

AI in technical writing is a tool, not a replacement. Just like how Google Docs didn't replace writers, AI won't replace technical writers. What it will do is change how we work.

In my technical writing projects, I use AI for specific tasks like generating initial API descriptions or creating basic how-to guides. But the real work of technical writing - understanding user needs, structuring information effectively, and creating clear learning paths - still requires human expertise.

How AI Tools Actually Work in Documentation

AI tools in technical writing work by processing existing documentation and generating new content based on patterns. This is useful for certain tasks but has clear limitations.

For example, when documenting a new API endpoint, AI can quickly generate a basic description and parameters list. However, it cannot understand the real-world use cases, common user mistakes, or which aspects need more detailed explanation based on user feedback.

Where Human Writers Excel

Human technical writers bring three critical elements that AI cannot replicate:

User Understanding
We understand our users' backgrounds, challenges, and needs. When I document a feature, I know our users' technical level and common pain points.
Context Integration
We can connect different pieces of information meaningfully. While documenting a payment API, I know which concepts need more explanation based on our user base.
Strategic Documentation Planning
We can plan documentation that aligns with business goals and user needs. This requires understanding both technical details and business context.

How to Adapt and Thrive

To thrive as a technical writer in the AI era, focus on these key areas:

Learn to Use AI Effectively
Use AI for initial drafts and routine tasks. This frees up time for more valuable work.
Focus on Strategic Skills
Develop skills in documentation planning, user research, and information architecture.
Build Technical Depth
Understand the technologies you're documenting deeply enough to identify what users really need to know.

Conclusion

AI is not making technical writers obsolete - it's making us more efficient and allowing us to focus on higher-value work. The key is understanding how to use AI effectively while developing the skills that remain uniquely human.

If you want to learn more about working effectively with AI in technical writing, feel free to reach out. I'm always happy to share specific examples and strategies.

How to Write a Troubleshooting Guide That Actually Helps Users

Elliot Brenya sarfo — Wed, 01 Jan 2025 09:45:00 +0000

Writing troubleshooting guides is a critical skill I've developed over the years. When I first started creating technical documentation, I made the classic mistake of writing guides that were technically accurate but practically useless. Our users would read through the entire guide and still end up contacting support for help.

That's when I realized something important which is , technical accuracy alone doesn't solve user problems. What matters is how we present solutions in a way that users can understand and implement.

I remember working on a complex API integration project where our support team was handling over 30 tickets daily. After implementing the documentation approach I'm about to share with you, we cut that number down to just 09 tickets per day. The secret? Making our troubleshooting guides actually work for users, not just exist as reference material.

In this article, I'll walk you through the exact process I use to create troubleshooting guides that reduce support tickets and help users solve problems on their own. This isn't theory - it's a practical approach I've refined through years of real-world application.

Understanding Your Audience: Beyond Basic Demographics

The first step in creating an effective troubleshooting guide is understanding your audience at a deeper level. Let me share a real scenario that changed my approach to audience analysis.

While working on documentation for a cloud deployment platform, I initially categorized users into the typical "technical" and "non-technical" groups. But after analyzing six months of support tickets and user interviews, I discovered something fascinating: 65% of our "technical" users were actually DevOps engineers who needed quick, command-line solutions, while 35% were senior developers who preferred detailed explanations of the underlying architecture.

This insight completely transformed our documentation strategy. Instead of writing one-size-fits-all guides, we started creating:

Quick Reference Guides: For DevOps engineers who needed immediate solutions
- Command-line snippets with minimal explanation
- Common error codes and their fixes
- Direct links to relevant API endpoints
Deep Dive Guides: For senior developers who wanted to understand the system
- Architectural diagrams
- System interaction flows
- Performance implications of different solutions
Guided Walkthroughs: For team leads who needed to train their teams
- Step-by-step tutorials with screenshots
- Common pitfalls and how to avoid them
- Best practices with real-world examples

The Art of Problem Description

One of the most critical elements of a troubleshooting guide is how you describe the problem. Let me share a technique that increased our guide's effectiveness by 80%.

Instead of the traditional approach:

Error: Connection timeout when deploying to production

We started using what I call the "Symptom-Impact-Context" framework:

Problem: Deployment to production fails with a connection timeout
Impact: Production deployments are blocked, potentially affecting release schedules
Context: Occurs most frequently during high-traffic periods (9 AM - 11 AM EST)
Common Triggers:
- Multiple concurrent deployments
- Network latency spikes
- Insufficient timeout settings

This framework helps users quickly identify if they're looking at the right guide and understand the severity of their issue.

Solution Architecture That Works

Through extensive A/B testing of our documentation, I've developed a solution presentation framework that significantly improves resolution rates. Here's the structure:

Quick Fix (Time: 5 minutes)
- For when you need an immediate solution
- Minimal steps, maximum impact
- Example: Increasing timeout values in config.json
Standard Resolution (Time: 15 minutes)
- Complete solution with proper checks
- Includes verification steps
- Example: Implementing retry logic with exponential backoff
Root Cause Fix (Time: 30+ minutes)
- Long-term solution addressing underlying issues
- Architectural improvements
- Example: Setting up a proper load balancing strategy

Each solution includes:

Prerequisites with exact versions
Command snippets that can be copied directly
Expected output at each step
Troubleshooting tips for common failure points

The Power of Context

Here's something I learned the hard way: users need context to trust a solution. Let me show you how I transform a basic solution into something more valuable:

Basic Approach:

Run: kubectl scale deployment myapp --replicas=3

Enhanced Approach:

Solution: Scale the deployment to handle increased load
Command: kubectl scale deployment myapp --replicas=3

Why This Works:
- Horizontal scaling distributes traffic across multiple pods
- Three replicas provide redundancy while maintaining reasonable resource usage
- Kubernetes' internal load balancer will automatically distribute requests

When to Use:
- During high traffic periods (>1000 requests/second)
- When response times exceed 200ms
- Before planned marketing campaigns

When Not to Use:
- If you're running on development clusters (use --replicas=1)
- If you have limited node resources
- During database migration periods

Testing That Actually Matters

The traditional approach to testing documentation (having a colleague review it) isn't enough. Here's the systematic testing framework I've developed:

Syntax Testing
- Run all commands in a clean environment
- Verify each code snippet
- Test with different OS versions
Comprehension Testing
- Have users from different technical backgrounds attempt the solutions
- Record time taken for each step
- Note questions asked during the process
Edge Case Testing
- Test solutions under load
- Verify behavior with different configurations
- Document failure scenarios and recovery steps

Maintaining Living Documentation

Documentation isn't a write-once task. I've implemented a maintenance system that keeps our guides relevant:

Automated Testing
- Weekly runs of all code snippets
- Automatic checks for deprecated APIs
- Version compatibility verification
User Feedback Loop
- Embedded feedback forms in each guide
- Monthly analysis of support tickets
- Quarterly user interviews
Version Control
- Git repository for documentation
- Change logs with justification
- Impact analysis for major changes

Final Words

Creating effective troubleshooting guides is a combination of technical knowledge, user psychology, and continuous refinement. The approaches I've shared here have been battle-tested across multiple projects and organizations.

Remember, your goal isn't just to document solutions - it's to empower users to solve problems confidently and independently. When done right, good documentation becomes a powerful tool for user success and team efficiency.

How to Write a Technical Article in 2025: Lessons From My 6-Year Journey

Elliot Brenya sarfo — Mon, 30 Dec 2024 21:18:36 +0000

When I started technical writing back in 2019, I never imagined how dramatically the landscape would change. After writing hundreds of articles and earning over $15,000 from technical content creation, I've learned that success in 2025's technical writing scene requires a completely different approach than what worked just a few years ago.

In this article, I'll share my battle-tested process that i will use in creating compelling technical content in 2025's AI-driven world. This isn't just theory it's what I use every day to write articles that consistently earn between $500 and $2,000 each.

Let me take you through my journey and show you exactly how I craft technical articles that resonate with both readers and clients.

The Evolution of Technical Writing

When I wrote my first technical article in 2019, it was enough to simply explain how something worked. Today, in 2025, that barely scratches the surface. I learned this lesson the hard way when one of my articles about React hooks got buried under thousands of AI-generated tutorials.

Here's what I have discovered will work in 2025:

Understanding the New Landscape

The first thing I tell every aspiring technical writer is this: you're not just competing with other writers anymore – you're competing with AI. But here's the secret I've learned: that's actually good news. Let me explain why.

Last month, I wrote an article about implementing WebAssembly in React. Instead of just explaining the technical steps, I shared my personal struggle with performance optimization and how WebAssembly solved our startup's critical rendering issues. That article earned $1,800 because it offered something AI couldn't: real experience and context.

The Modern Technical Writing Process

After writing over 500 technical articles, I've developed a process that consistently produces high-quality content that stands out in 2025's crowded landscape. Here's my exact workflow:

1. Experience-First Research
I no longer start with Google searches. Instead, I begin by implementing the technology I'm writing about in a real project. For example, when writing about GraphQL subscriptions recently, I built a small real-time chat application first. This gave me insights that no amount of documentation reading could provide.

// Real code from my chat application
const ChatSubscription = () => {
  const { data, loading, error } = useSubscription(
    NEW_MESSAGE_SUBSCRIPTION,
    {
      onData: ({ data }) => {
        // Here's where I discovered a crucial limitation
        // that became the centerpiece of my article
        if (data.newMessage.timestamp < lastProcessed) {
          handleOutOfOrderMessage(data.newMessage);
        }
      }
    }
  );
}

This code snippet became the foundation for a section about handling out-of-order messages in GraphQL subscriptions – a real problem I encountered that wasn't covered in any documentation.

2. Personal Story Integration
Every technical article I write now includes at least one personal story. Here's how I structure these narratives:

The Problem Setup:
"Last sprint, our team faced a critical issue: our React application was taking 8 seconds to load on mid-range mobile devices. Our analytics showed we were losing 23% of users during this initial load."

The Journey:
"We tried code splitting, lazy loading, and even rewrote our state management. Nothing moved the needle significantly. Then, during a late-night debugging session, I discovered something interesting about how our components were handling data transformations..."

The Solution:
"By moving these transformations to a Web Worker, we cut our load time to 2.3 seconds. Here's exactly how we did it..."

3. Code-First Explanations
In 2025, with AI generating perfect documentation-style content, I've found that showing real, messy code first, then explaining it, works better than traditional top-down explanations.

// Real code from our production app
const useOptimizedTransform = (rawData) => {
  const workerRef = useRef();

  useEffect(() => {
    // This was our first attempt - it had issues
    workerRef.current = new Worker('/transform.worker.js');

    // We had to add this error boundary later
    const timeoutId = setTimeout(() => {
      if (!workerRef.current) {
        console.error('Worker failed to initialize');
        fallbackToMainThread(rawData);
      }
    }, 2000);

    return () => {
      clearTimeout(timeoutId);
      workerRef.current?.terminate();
    };
  }, []);

  // More real-world complexity...
}

4. The Reality Check Section
Every article I write now includes a section about what can go wrong. This has become my signature style because it's something AI-generated content rarely covers well. For example, in my WebAssembly article:

"After implementing WebAssembly, we discovered three critical issues:

Our debugging tools no longer worked as expected
The build process became significantly more complex
Some team members struggled with the new paradigm

Here's how we addressed each issue..."

5. Future-Proofing Your Content
One lesson I learned the hard way: technical content in 2025 needs to be future-proofed. I now include a section in every article about potential future changes and how to adapt to them.

For instance, when writing about React Server Components, I include:

// Current approach (2025)
const ServerComponent = async () => {
  const data = await fetchData();
  return <DataDisplay data={data} />;
}

// Preparing for future changes
const ServerComponent = async ({ signal } = {}) => {
  const data = await fetchData({ signal });
  return (
    <ErrorBoundary fallback={<ClientFallback />}>
      <DataDisplay data={data} />
    </ErrorBoundary>
  );
}

Monetization in 2025

Let me be transparent about the business side of technical writing in 2025. Here's my current revenue breakdown:

Direct client articles: $500-$2,000 per article
Platform revenue sharing: $200-$800 per article

The key to these numbers isn't just technical knowledge rather it's the ability to combine technical expertise with authentic experiences and insights.

Common Pitfalls to Avoid

I've made plenty of mistakes along the way. Here are the biggest ones I will tell you to avoid in 2025:

Over-relying on AI tools for content generation
Not including enough real-world scenarios
Writing for search engines instead of humans
Skipping the implementation phase
Not addressing the "why" behind technical decisions

Final Note

Technical writing in 2025 will be more challenging but also more rewarding than ever. The key is to embrace your humanity, share your experiences, struggles, and real-world implementations. That's something AI can't replicate.

Remember: Your greatest asset as a technical writer isn't just your technical knowledge, it's your experience and your ability to connect with readers through authentic stories and real-world examples.

You might want to;

Start documenting your technical challenges
Build a portfolio of real implementations
Develop your unique writing voice
Network with other technical writers
Never stop learning and experimenting

The future of technical writing belongs to those who can blend technical expertise with authentic human experience.

P.S. Feel free to connect with me on Twitter or LinkedIn to discuss more about technical writing. I'm always happy to help fellow writers succeed in this evolving landscape.