Bruno Pedro's public notes
September, 2023
Permalink: 20230924192417
Found at “rberenguelPiWrite: Use your Kindle Paperwhite as a writing device” on 2023-09-24 19:24:17 +02:00.
Have you ever wanted to use your Kindle Paperwhite to write, even more, with a vim-like editor? This is what PiWrite is for.
Permalink: API naming conventions and code generation
Naming conventions play a crucial role in the quality of the SDK that you generate for your API. Here are some examples of naming conventions for a few API architectural styles:
- Plural nouns to represent REST resources, e.g., /articles.
- Use of HTTP verbs to access REST endpoints, e.g., POST /articles.
- Singular nouns to represent data types in GraphQL, e.g., Article.
- Use of verbs for GraphQL mutations, e.g., CreateArticle.
- Using the word “service” to identify gRPC services, e.g., ArticleService.
- Verb-noun structure to define event names in asynchronous APIs, e.g., ArticleCreated.
If you decide to follow a different structure—or don’t follow any structure at all—the SDK you generate will be harder to use by developers. As an example, the OpenAPI operationId attribute should be named in a way that works well across the programming languages that you want to support. The OpenAPI specification even recommends that:
Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.—OpenAPI specification 3.1.0 § Operation Object
So, it’s important to pay attention to how you’re naming things on your API so consumers have the best possible experience.
Permalink: Building the apidays API
I’m building an API product for the apidays conferences.
I’m starting my journey of building a new API. After a great discussion with Mehdi Medjaoui, we aligned on the vision for what is to become the apidays API:
To offer the best possible experience to attendees before, during, and after a conference.
I already have some ideas for features but I won’t get ahead of myself. Instead, I want to engage with stakeholders—past and future conference attendees, speakers, and organizers—to learn their challenges and how the API can help them.
I’m working in public so I’ll be sharing my progress here with pointers to any code, documentation, and other assets produced during the process.
Permalink: API deployment options
How do you deploy your API?
One of the challenges that I’ve been hearing is related to API deployment to different environments. Specifically, how do you decide what environments to have, what technologies to use, and how to automate the deployments?
From my experience, the environments you have depend on the stage of your company and the stage of your API. Here are some examples of different maturity stages:
- API Design: if you’re validating an API Design with stakeholders you can simply use a mock server. You can build one yourself or use any available tools. If you choose to use an existing tool you don’t have to deploy anything.
- API Prototype: at this stage, you probably want to launch a minimal environment that lets stakeholders experiment with your API. This environment should help you detect performance bottlenecks and understand what you need to improve in a real production system.
- API QA: I recommend that you have a dedicated environment just for QA. Why? Because many types of QA tests are destructive and you wouldn’t want to do that in a production environment. The QA environment should resemble as much as possible your final production environment.
- API Deployment: The stage that most people look forward to is the one where you finally have your API generally available. The production environment should be built from the learnings of the prototype stage and fixing any issues detected during QA.
Other than these, some companies also use a development environment that teams use to test what they’re building. Local environments are also helpful because they help developers test their code on their own machines.
Permalink: 20230921114728
Found at “Grouping digits in SQL | Peter Eisentraut” on 2023-09-21 11:47:28 +02:00.
One of the minor new features in PostgreSQL 16 that I am excited about is the ability to group digits in numeric literals by separating them with underscores
Permalink: 20230920175420
Found at “Streaming Databases: Everything You Wanted to Know” on 2023-09-20 17:54:20 +02:00.
the ability to harness real-time data has become essential for organizations striving to make informed decisions and remain competitive. This comprehensive guide explores the world of streaming databases, shedding light on their distinct characteristics and advantages in handling streaming data.
Permalink: Finding product and engineering alignment in highly technical companies
Last week I was having a call with a product leader in a technical company. We were discussing the challenges of aligning product and engineering to drive a very technical product.
One of the challenges is related to the nature of the product. With a very technical product, it’s natural that engineers feel ownership. Additionally, product managers need to be very technical or fail to even understand their target users.
How do you find alignment and drive the company forward in this reality? One way is to follow the practice of stream-aligned teams, as described by Manuel Pais in the book “Team Topologies.” The goal is to use cross-functional teams where different members collaborate to reach a goal. According to Manuel, there’s one big advantage of using such teams:
(…) because stream-aligned teams are composed of people with various skills, there is a strong drive to find the simplest, most user-friendly solution in any given situation. Solutions that require deep expertise in one area are likely to lose against simpler, easier-to-comprehend solutions that work for all members of the stream-aligned team.
Also, all members learn from each other. Even product managers who aren’t very technical will end up learning from engineers.
Permalink: 20230918120751
Found at “What If OpenDocument Used SQLite?” on 2023-09-18 12:07:51 +02:00.
using SQLite as a container for an application file format like OpenDocument and storing lots of smaller objects in that container works out much better than using a ZIP archive holding a few larger objects
Permalink: 20230916185156
Found at “Relational is More than SQL” on 2023-09-16 18:51:56 +02:00.
Most people think of SQL and the relational model as synonymous, which is sensible because of SQL’s long-term dominance. However, they are not the same thing.
Permalink: 20230916185041
Found at “A Different Type of SQL Recursion with PostgreSQL · vb-consultingblog · Discussion #1” on 2023-09-16 18:50:41 +02:00.
PostgreSQL offers a powerful procedural programming model out of the box (in addition to the standard SQL).
Permalink: 20230915152947
Found at “The mathematical reason why agencies get stuck at $50k MRR – Jakob Greenfeld – Experiments in Permissionless Entrepreneurship” on 2023-09-15 15:29:47 +02:00.
Every agency gets stuck around $50k in monthly revenue. Hardly anyone ever breaks through that barrier and reaches that next level where the agency generates reliably $300k+ in monthly revenue.
Permalink: API AARRR funnel
DX is just part of the story when it comes to managing an API product.
Following the AARRR funnel, these are the factors that influence each step of the way:
- DX influences acquisition and activation: Developers build integrations with an API once so they don’t have power over the retention of second-degree users (people who use your API indirectly through an integrated application). Activation is also influenced by DX through authentication and authorization. Use something like API keys and users will find it hard to start using your API. With something like OAuth, things will be easier.
- API UX influences retention and referral: Alignment with the needs of consumers makes them use an API repeatedly. Being available on the tools that consumers use, and following the architectural style that best adapts, makes using the API a joy. Happy users who obtain value from an API will refer it to others.
- VX influences revenue: Being able to align the value you’re offering to consumers with your monetization model will enable a stream of revenue. Consumers who extract the right value from an API will be open to paying for using it.
I’ve been exploring this area and I’m synthesizing my findings in this framework.
Permalink: 20230913192626
Found at “Quick insights using sqlelf | Farid Zakaria’s Blog” on 2023-09-13 19:26:26 +02:00.
Declarative languages, such as SQL, are such a wonderful abstraction to articulate over data layouts and let you reason about what you want rather than how to get it.
Permalink: 20230910182235
Found at “nginxunit: NGINX Unit – universal web app server – a lightweight and versatile open source server project that works as a reverse proxy, serves static assets, and runs applications in multiple languages.” on 2023-09-10 18:22:35 +02:00.
NGINX Unit is a lightweight and versatile open-source server
Permalink: 20230908145726
Found at “What is a Query Engine? - How Query Engines Work” on 2023-09-08 14:57:26 +02:00.
A query engine is a piece of software that can execute queries against data to produce answers to questions
Permalink: Increasing API retention
What increases the retention of users consuming your API?
Developer Experience (DX) influences acquisition and activation, value exchange (VX) influences monetization, and user experience (UX) influences retention.
One way UX increases retention is by reducing the friction regular users find to start and keep using your API. One way to reduce friction is by choosing the right architectural style based on what users need, not on your preferences. Another way is to use authentication and authorization mechanisms that are simple to understand and use, such as OAuth.
OAuth provides the easiest form of authentication and authorization for users who want to integrate your API with the tools they already use. By being able to securely have your API working inside their favorite tools, users will keep using your API regularly with little or no friction at all.
Permalink: Platform business
How can you create a platform business by enabling a two-sided market?
First, let’s see what a platform business is:
- Creates value by facilitating interactions and transactions between multiple groups, typically known as “sides.”
- The “sides” can be producers, consumers, or other participants who benefit from the platform’s services and network effects.
- Network effects create a virtuous cycle where growth attracts more participants to all sides of the platform.
- Revenue is generated through monetization models that include transaction fees and subscriptions.
Examples of platform businesses include Airbnb, YouTube, and Uber, among others.
So, how do you enable a two-sided market?
- Increasing active usage: User commitment and active usage, not sign-ups or acquisitions, are the true indicators of customer adoption.
- Offering participation incentives: Users who participate obtain value that is organically aligned with the interactions made possible by the platform.
- Improving the UX: Every user interaction must be frictionless, including those done via an API.
APIs can help with the creation of a platform. However, they’re not the only thing you need to consider when attempting to move into this type of business.
Permalink: 20230907110329
Found at “New LoRa world record: 1336 km 830 mi” on 2023-09-07 11:03:29 +02:00.
New LoRa world record: 1336 km / 830 mi
After 3 years, the new world record was set by installing LoRaWAN trackers on a fishing boat Estrela de Sesimbra and on its buoys on the Sesimbra coast, Portugal. The tracker was able to make contact with a gateway in the Canarian Islands. Three messages have been received by the “cablpa-pitilleros” gateway connected to The Things Stack Community Edition.
Permalink: 20230906114148
Found at “Cory Doctorow: Interoperability Can Save the Open Web - IEEE Spectrum” on 2023-09-06 11:41:48 +02:00.
the third kind of interop, the kind of chewy, interesting, lots-of-rich-Internet-history interop, which is adversarial interoperability, which in the book we call “comcom,” short for competitive compatibility. It’s the interop that’s done against the wishes of the original equipment manufacturer: scraping, reverse engineering, bots, all of that gnarly stuff done in the face of active hostility.
Permalink: 20230906113727
Found at “RecipeUI” on 2023-09-06 11:37:27 +02:00.
RecipeUI is the open source Postman alternative with type safety built in.
Permalink: DX, VX, or API UX?
DX, VX, or API UX? Which one is more important?
This is how I see it:
- DX drives acquisition: Most developers only interact with your API once when they’re building the integration code. After that, the integration (hopefully) keeps running and developers won’t interact with your API again.
- VX drives revenue: By aligning your API with your business objectives you’ll have a better chance of monetizing and generating revenue. Without VX you can have a fantastic API but you might not be able to sustain it from a business perspective.
And, finally, my favorite:
- API UX drives retention: Consumers (not just developers) have been interacting with APIs more and more on a regular basis. AI is an excellent example of how non-technical people can use APIs regularly, sometimes without even realizing it. A negative API UX introduces friction makes it hard for consumers to obtain value from the API, and increases churn.
As an organization, I’d say that these three experiences are essential. However, prioritizing the one that matters the most to you is crucial to find success.
So, ask yourself where you are in your API program and select which experience you should focus on to achieve results.
Permalink: 20230905125041
Found at “keephqkeep: The open-source alerts management and automation platform” on 2023-09-05 12:50:41 +02:00.
Keep makes it easy to consolidate all your alerts into a single pane of glass and to orchestrate workflows to automate your end-to-end processes.
Permalink: 20230905121643
Found at “In Praise of the Meandering Career - Every” on 2023-09-05 12:16:43 +02:00.
The greatest benefit of a nontraditional path is that you have to figure out what you care about. Rather than an employer telling you what you should value, you have to do the hard work of determining what you value for yourself.
Permalink: 20230905114927
Found at “A Company of One. - by Rishad Tobaccowala” on 2023-09-05 11:49:27 +02:00.
Whether it is finding work post-retirement, working a side-hustle or passion project to make ends meet or build an expertise or create an off-ramp, or filling the gaps between full-time employment at firms which are often trigger-happy in adding and removing talent from their payrolls, the smart professional prepares to be a company of one.
Permalink: 20230904181420
Found at “Jade Rubick - Leaders make their own problems” on 2023-09-04 18:14:20 +02:00.
If you want to lead, you have to learn to make your own problems. You want the problems you’re working on to be partially something you’ve generated.
Permalink: 20230904173623
Found at “RFC 6570 - URI Template” on 2023-09-04 17:36:23 +02:00.
A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion.
Permalink: 20230904173554
Found at “URI Template Router: Introduction” on 2023-09-04 17:35:54 +02:00.
URI Template Router supports expansion for of the features of RFC 6570 URI templates, and pattern matching for most of the features that are reversible.
Permalink: 20230903153427
Found at “LoraPaper Is a Connected ePaper Device That Runs Entirely on Light - Hackster.io” on 2023-09-03 15:34:27 +02:00.
LoraPaper is an E Ink unit that connects to the Internet, displays information, and only requires ambient light to function.
Permalink: 20230902205342
Found at “Open-sourcing SQX, a way to build flexible database models in Go - Stytch” on 2023-09-02 20:53:42 +02:00.
Mapping between database rows and in-memory structs can be difficult. The SQX library is a powerful tool that simplifies the process of creating flexible database interfaces.
Permalink: 20230902201854
Found at “Foreword by Mike Amundsen” on 2023-09-02 20:18:54 +02:00.
hypermedia is a powerful approach to creating computer systems that enable people to work together for the common good.
Permalink: 20230901095426
Found at “Fine-tuning GPT-3.5-Turbo for Natural Language to SQL | by Mo Pourreza | Dataherald | Aug, 2023 | Medium” on 2023-09-01 09:54:26 +02:00.
Allowing non-technical users to ask questions from a database has been a problem of interest in academia and industry for years.
August, 2023
Permalink: Sea & Mountain
Permalink: Docker is 4 things
Found at “Matthias Portzel – Docker is 4 things” on 2023-08-31 15:24:16 +02:00.
- First, the Dockerfile file format for declaratively describing a machine (operating system, installed packages, processes, etc).
- Second, the Docker Engine which takes a Dockerfile and runs it on a Linux host natively, without a virtual machine.
- Third, the Docker Desktop app which takes a Dockerfile and runs it on a Mac or Windows host, using a Linux virtual machine.
- Fourth, the Docker Hub container repository which allows a community to share Dockerfiles for common configurations.
Often, when people evaluate Docker or make statements about “Docker,” they’re referring only to the Docker Engine. But most of the time, this is not a useful view to take. Most of time, the practicality of Docker comes from a combination of all four of these things.
Permalink: 20230830155705
Found at “Google Maps Platform Documentation | Air Quality API | Google for Developers” on 2023-08-30 15:57:05 +02:00.
The Air Quality API allows you to request air quality data for a specific location
Permalink: Immediacy and procrastination
PBers (1)Procrastinators and blockers. favor speed and immediacy over accuracy and constancy. PBers are generally more concerned about trying to manage short-term comfort than long-term effectiveness in solving important problems. So, to control their emotions, they procrastinate and block.—in PROCRASTINATION AND BLOCKING: A Novel, Practical Approach, Robert Boice
Permalink: 20230826123115
Found at “Prof. Robert Boice’s Rules of the Road for Writers” on 2023-08-26 12:31:15 +02:00.
Start before you feel ready. Stop before you feel done.
Permalink: 20230822150248
Found at “SmartBear to Acquire Stoplight to Deliver Industry’s Broadest Portfolio of API Development Capabilit” on 2023-08-22 15:02:48 +02:00.
SmartBear’s acquisition of Spotlight augments its API lifecycle management offering to help developers create more reliable APIs that can better align with a company’s objectives
Permalink: Rules for life
- Always be ready to reinvent yourself. Stay foolish for as long as you can, always in learning mode.
- Act immediately when you feel inspired. Take advantage of your mood to act, don’t overthink it.
- Don’t adjust yourself to please others. Be yourself, follow your own rules, live with the consequences.
- Be minimal about the things you need. Don’t overspend on things you don’t really need, live a frugal life.
- Own your life. Don’t be a slave to a wage, be a master of your time and your life.
Permalink: 20230820160416
(…) what we both like about drawing is the sense of immediacy. It’s very quick because we finish a drawing in maybe even a few seconds.
Permalink: 20230818174412
Found at “An Introduction to Statistical Learning” on 2023-08-18 17:44:12 +02:00.
An Introduction to Statistical Learning provides a broad and less technical treatment of key topics in statistical learning. This book is appropriate for anyone who wishes to use contemporary tools for data analysis.
Permalink: 20230817175754
Found at “Developing on Remote Machines using SSH and Visual Studio Code” on 2023-08-17 17:57:54 +02:00.
The Visual Studio Code Remote - SSH extension allows you to open a remote folder on any remote machine, virtual machine, or container with a running SSH server and take full advantage of VS Code’s feature set.
Permalink: 20230816150855
Found at “Introducing Zapier’s new Visual Editor” on 2023-08-16 15:08:55 +02:00.
You’ve built fantastic workflows to run your businesses and keep raising the bar. To keep pace with your innovations, we designed the new editor to be more intuitive and help you build advanced automations even faster.
Permalink: 20230814172643
Found at “AddyOsmani.com - Write about what you learn. It pushes you to understand topics better.” on 2023-08-14 17:26:43 +02:00.
Writing about what you learn is more than just a method of documentation; it’s a powerful tool for deepening understanding and revealing the gaps in one’s knowledge.
Permalink: 20230812182036
I just set up my first 3D printer. I intend to use mostly for prototyping and experimentation.
Permalink: 20230812181649
Found at “Scripting News: Bootstrapping an app ecosystem” on 2023-08-12 18:16:49 +02:00.
Today it’s virtually impossible for an independent developer, without millions in venture capital, to launch a new product or service.
Permalink: 20230812175532
It’s interesting that API Product Management is gaining adepts. The trend reminds me of something I wrote in 2019 about non-technical API Design tools:
Why aren’t companies building API Design tools that make it easier for non-technical people to collaborate in the API Design activities?
I feel that these tools aren’t yet available. Why not?
Permalink: 20230811223823
Found at “Why are API Product Managers Hard to Find?” on 2023-08-11 22:38:23 +02:00.
API product management is a unique and nuanced form of software product management. Finding the right help that “speaks” API can be challenging but can significantly improve the likelihood of an API’s success.
Permalink: 20230807174640
I remember that one of my most productive times was in ca. 1995 while building a campus-wide POS system involving a long-distance wireless network, hardware, and custom-built software that ran on low-end PCs with touch-screen displays.
I was working from Monday to Thursday starting at 9 in the morning and ending at 12 pm. The afternoons were devoted to spending time with friends, exploring ideas, and reading. We made sure that we didn’t do any work in afternoons and waited, on purpose, until the next morning. All mornings were highly productive and focused on what mattered.
Permalink: 20230807174514
Found at “Edsger Dijkstra’s One-Day Workweek - Cal Newport” on 2023-08-07 17:45:14 +02:00.
Busyness is not the engine of production. It can, in many cases, instead be the obstacle to accomplishing your best work.