Tags

Tag: communication

notes

Navigating Ambiguity with Questions

Here’s my process for using questions to navigate ambiguity: Start with a “question dump” Organize by power Seek answers systematically Iterate and refine Document and share https://alifeengineered.substack.com/p/the-art-of-dealing-with-ambiguity

notes

US Tech Leadership and Culture

In the US, being soft-spoken, deferential, and respectful makes you a valued colleague, NOT a leader. America was born in revolution, has an enduring cowboy identity, and today is led by a reality TV personality. This pattern plays out in business, too. US business culture favors those who speak quickly, act boldly, and ignore at least some rules and limitations. If anything, this trend is increasing with ideas like “founder mode” getting broad attention and support

notes

Writing for Thought vs Audience

The text you write for thinking should differ from the text you write for others to read.

notes

Respectful Disagreements

When you disagree with someone in words while being truly agreeable in demeanor, many people will match your conduct. They will discuss with you rather than attack you.

notes

Prime directive

Engineers, although they may have better ideas or insights, their communication style generates resentment that will limit how much impact they can have in the future. Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.

notes

Status reports

A status report is what others need to know, not what you did. A status report communicates important things (from a stakeholder’s perspective), not all the work.

notes

Customer complaints

When a customer brings a complaint, there are always two tokens on the table: “It’s no big deal” and “It’s the end of the world”. Both tokens are always played, so whoever chooses first forces the other to grab the token that’s left. Don’t force your customer into taking the “It’s the end of the world” one. https://brunopedro.com/

Tag: problem-solving

notes

Navigating Ambiguity with Questions

Here’s my process for using questions to navigate ambiguity: Start with a “question dump” Organize by power Seek answers systematically Iterate and refine Document and share https://alifeengineered.substack.com/p/the-art-of-dealing-with-ambiguity

notes

Key Skills for Software Engineers

Using natural language (or diagrams) to describe how to break down and precisely solve a novel problem (scalably and securely) is not easy and never will be easy. The key skills needed for software engineering are: requirements gathering / analysis, abstraction, data modelling / ontology building, algorithms, modularity / separation of concerns, team building / communication, threat modelling / security, debugging / problem determination, operations and monitoring, and ultimately… Not Building The Wrong Thing.

notes

5 Whys

You can get to the real cause of an issue by asking why 5 times.

notes

Customer complaints

When a customer brings a complaint, there are always two tokens on the table: “It’s no big deal” and “It’s the end of the world”. Both tokens are always played, so whoever chooses first forces the other to grab the token that’s left. Don’t force your customer into taking the “It’s the end of the world” one. https://brunopedro.com/

Tag: process

notes

Navigating Ambiguity with Questions

Here’s my process for using questions to navigate ambiguity: Start with a “question dump” Organize by power Seek answers systematically Iterate and refine Document and share https://alifeengineered.substack.com/p/the-art-of-dealing-with-ambiguity

Tag: questions

notes

Navigating Ambiguity with Questions

Here’s my process for using questions to navigate ambiguity: Start with a “question dump” Organize by power Seek answers systematically Iterate and refine Document and share https://alifeengineered.substack.com/p/the-art-of-dealing-with-ambiguity

Tag: management

notes

Yearly Progress in Weeks

Every week is 2% of a year

notes

Trust yet verify

Your management chain is responsible for ensuring the success of your projects. “Trust yet verify” is the magic phrase which accounts for this type of ownership. You preferably trust your employees, but you need to verify that things are going well.

notes

Procrastinators

Procrastinators and blockers favor speed and immediacy over accuracy and constancy. 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. https://brunopedro.com/

notes

Ownership in Tech

In all cases, you should push decisions as far down your org chart as they can go. Consider how much pain and inefficiency you’re willing to take, in exchange for people feeling ownership over their goals and mission. I’d enjoy dictating exactly how our new dashboard should operate, but it’s in our organization’s best interest to let the dashboard team make those decisions. If I dictate their work, they’ll execute on it.

notes

Slightly above

When people are placed in positions slightly above what they expect, they are apt to excel.

notes

Heilmeier Catechism

What are you trying to do? Articulate your objectives using absolutely no jargon. How is it done today, and what are the limits of current practice? What is new in your approach, and why do you think it will be successful? Who cares? If you are successful, what difference will it make? What are the risks? How much will it cost? How long will it take? What are the mid-term and final “exams” to check for success?

notes

Celebrating milestones

Progress begets progress, which is why celebrating milestones and team culture in the form of stories and surprises that become folklore are critical. This is the stuff that keeps a team together long enough to figure it out. Without these elements of adventure, building a company or any other bold project feels like you’re on a treadmill and will be harder. https://www.linkedin.com/pulse/10-thoughts-running-leading-teams-building-products-scott-belsky/?trackingId=8qfNtJKfSI%2BhaJO9%2BNLhmg%3D%3D

notes

Three Lenses to look at a problem strategically

Lens 1: The person In what ways (if any) might the individual be contributing to the problem? (Things like their workstyle, lack of skill, motivation, clarity.) Lens 2: You In what ways (if any) might you be contributing to the problem? (Maybe you didn’t provide feedback, didn’t set clear expectations.) Lens 3: The team/ organisation In what ways (if any) might the team/organisation/systems be contributing to the problem? (Things like interdependencies, unclear processes, conflicting priorities.

notes

Common Strategy Mistakes

Common mistakes that teams make when not thinking strategically: Focusing on the wrong priorities Focusing on the wrong outcome Not involving the right people at the right time Not seeing the bigger picture Not anticipating problems Not understanding how one project impacts another Working without thinking through why the work is being done Diving into work without thinking if it’s already been solved before Working and getting feedback only at completion (not earlier) Not converting ideas into action in efficient ways

notes

Bad Strategy

Bad strategy ignores the power of choice and focus, trying instead to accommodate a multitude of conflicting demands and interests. Like a quarterback whose only advice to his teammates is “Let’s win,” bad strategy covers up its failure to guide by embracing the language of broad goals, ambition, vision, and values. As seen in: https://www.mckinsey.com/capabilities/strategy-and-corporate-finance/our-insights/the-perils-of-bad-strategy

notes

Rules for hard conversations

Get your emotions under control Ask at a good time Do not ambush Be open to where you can grow Avoid it if it’s simply true

notes

Mentoring and coaching

You might step into a mentoring mode when you are sharing your experiences, offering advice and knowledge. If you’re a leader in tech, you likely overindex on mentoring because it’s easy. Because you’re proud of your expertise and you want to share and help. Often, a more appropriate mode is to use a coaching mode. In coaching, you careful listen, ask questions and you help someone uncover their own approach to their own problem/challenge.

notes

On feedback

When people tell you something is wrong, they’re usually right. When they tell you how to fix it, they’re usually wrong.

Tag: planning

notes

Yearly Progress in Weeks

Every week is 2% of a year

Tag: productivity

notes

Yearly Progress in Weeks

Every week is 2% of a year

notes

Time to Market and noise

We knew time to market was a priority and wanted to shield the team from noise.

notes

Procrastinators

Procrastinators and blockers favor speed and immediacy over accuracy and constancy. 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. https://brunopedro.com/

notes

Effective Estimations

Estimations are useful in high level discussions about feasibility and underlying technical complexities (like, is this a week or a month, and why?), and also to be able to make trade-offs between quick wins and larger investments. But estimating down to the story point or man-hour is a huge waste of everyone’s time and sanity.

Tag: time

notes

Yearly Progress in Weeks

Every week is 2% of a year

Tag: business-culture

notes

US Tech Leadership and Culture

In the US, being soft-spoken, deferential, and respectful makes you a valued colleague, NOT a leader. America was born in revolution, has an enduring cowboy identity, and today is led by a reality TV personality. This pattern plays out in business, too. US business culture favors those who speak quickly, act boldly, and ignore at least some rules and limitations. If anything, this trend is increasing with ideas like “founder mode” getting broad attention and support

Tag: leadership

notes

US Tech Leadership and Culture

In the US, being soft-spoken, deferential, and respectful makes you a valued colleague, NOT a leader. America was born in revolution, has an enduring cowboy identity, and today is led by a reality TV personality. This pattern plays out in business, too. US business culture favors those who speak quickly, act boldly, and ignore at least some rules and limitations. If anything, this trend is increasing with ideas like “founder mode” getting broad attention and support

notes

Respectful Disagreements

When you disagree with someone in words while being truly agreeable in demeanor, many people will match your conduct. They will discuss with you rather than attack you.

notes

The Strategy Tax

The problem that big, established companies get into is what is referred to as the strategy tax. This is basically the fact that they have to sort of fit their next big thing into their existing agenda. And they often compromise in the process.

notes

Team initiatives

Setup a rotation Invite one person of the team to lead the initiative each time

notes

Prime directive

Engineers, although they may have better ideas or insights, their communication style generates resentment that will limit how much impact they can have in the future. Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.

notes

Trust yet verify

Your management chain is responsible for ensuring the success of your projects. “Trust yet verify” is the magic phrase which accounts for this type of ownership. You preferably trust your employees, but you need to verify that things are going well.

notes

Cultural Change

If you’re trying to make a cultural change, I’ve found it’s much easier to reinforce desired behaviours than to focus on feedback on undesirable behaviours.

notes

Time to Market and noise

We knew time to market was a priority and wanted to shield the team from noise.

notes

Ownership in Tech

In all cases, you should push decisions as far down your org chart as they can go. Consider how much pain and inefficiency you’re willing to take, in exchange for people feeling ownership over their goals and mission. I’d enjoy dictating exactly how our new dashboard should operate, but it’s in our organization’s best interest to let the dashboard team make those decisions. If I dictate their work, they’ll execute on it.

notes

Stategic pitfall

The best way to undercut a strategic initiative is to make it someone’s part-time job.

notes

Popovic mentoring style

The sooner you make someone feel responsible and confident that they can do something, the better. Then, you wait to see if they respond. Then you know you have chosen the right one.

notes

Decision tiers

Some decisions are consequential and irreversible or nearly irreversible – one-way doors – and these decisions must be made methodically, carefully, slowly, with great deliberation and consultation. If you walk through and don’t like what you see on the other side, you can’t get back to where you were before. We can call these Type 1 decisions. But most decisions aren’t like that – they are changeable, reversible – they’re two-way doors.

notes

Slightly above

When people are placed in positions slightly above what they expect, they are apt to excel.

notes

Heilmeier Catechism

What are you trying to do? Articulate your objectives using absolutely no jargon. How is it done today, and what are the limits of current practice? What is new in your approach, and why do you think it will be successful? Who cares? If you are successful, what difference will it make? What are the risks? How much will it cost? How long will it take? What are the mid-term and final “exams” to check for success?

notes

Fear of change

It is much easier to imagine negative consequences than the positive possibilities of a change. Humans are wired to first think about the risks as a survival trait.

notes

Celebrating milestones

Progress begets progress, which is why celebrating milestones and team culture in the form of stories and surprises that become folklore are critical. This is the stuff that keeps a team together long enough to figure it out. Without these elements of adventure, building a company or any other bold project feels like you’re on a treadmill and will be harder. https://www.linkedin.com/pulse/10-thoughts-running-leading-teams-building-products-scott-belsky/?trackingId=8qfNtJKfSI%2BhaJO9%2BNLhmg%3D%3D

notes

Leadership

Only three things happen naturally in organizations: friction, confusion, and underperformance. Everything else requires leadership.

notes

Change stakeholders

‘Who’ questions to ask when leading change: The included: Who else could be or needs to be included in what I’m doing? The informants: Who has done things like this in the past that I can lean on for support? The advisors: who could I get advice from or interview to get more insight? The creatives: Who comes from a different field of work, and could add a creative angle to my change?

notes

Goodhart Law

Employees are smart enough to know that if a measure is used to evaluate them, then they should optimize that measure. This is captured by Goodhart’s Law: “When a measure becomes a target, it ceases to be a good measure.”

Tag: security

notes

Key Skills for Software Engineers

Using natural language (or diagrams) to describe how to break down and precisely solve a novel problem (scalably and securely) is not easy and never will be easy. The key skills needed for software engineering are: requirements gathering / analysis, abstraction, data modelling / ontology building, algorithms, modularity / separation of concerns, team building / communication, threat modelling / security, debugging / problem determination, operations and monitoring, and ultimately… Not Building The Wrong Thing.

notes

Advanced Encryption Standard

The Advanced Encryption Standard (AES) is a specification for how electronic data should be encrypted that was published by the National Insitute for Standards in Technology (NIST) in the U.S. in 2001 https://www.thoughtworks.com/insights/blog/privacy/illustrated-guide-advanced-encryption-standard?utm_medium=email&utm_source=marketo&mkt_tok=MTk5LVFERS0yOTEAAAGTfWHXbMeay5dEA78XJDcrELbG96ewhrXEctQc2eHKwAZXhDiPTQAc3VfKce7JKG_WxHuTk8JSwgDCi3K26nb3Zo9UfC7qi7F7eGy_k_KMJVVombQ

Tag: skills

notes

Key Skills for Software Engineers

Using natural language (or diagrams) to describe how to break down and precisely solve a novel problem (scalably and securely) is not easy and never will be easy. The key skills needed for software engineering are: requirements gathering / analysis, abstraction, data modelling / ontology building, algorithms, modularity / separation of concerns, team building / communication, threat modelling / security, debugging / problem determination, operations and monitoring, and ultimately… Not Building The Wrong Thing.

Tag: software-engineering

notes

Key Skills for Software Engineers

Using natural language (or diagrams) to describe how to break down and precisely solve a novel problem (scalably and securely) is not easy and never will be easy. The key skills needed for software engineering are: requirements gathering / analysis, abstraction, data modelling / ontology building, algorithms, modularity / separation of concerns, team building / communication, threat modelling / security, debugging / problem determination, operations and monitoring, and ultimately… Not Building The Wrong Thing.

Tag: api-design

notes

Simplicity principle

The API design should be simple and easy to understand By avoiding unnecessary complexity and layers of abstraction we can create a more maintainable API that minimizes confusion and encourages correct usage by API consumers. The API design aims for the best possible orthogonality, meaning tha the minimum set of primitive constructs can be combined in a relatively small number of ways to build the control and data structures of the API.

services

Solution architecture manager - Groupama

Mr. Gkoros provided valuable guidance to our team, enhancing our API design skills and supporting us in managing our expanding API landscape effectively. His support enabled both Developers and Solution Architects to focus and gain a deeper understanding of designing APIs and establishing a strong governance model. Solution architecture manager - Groupama

notes

API Design as Communication

An API Design app is a chat app

notes

Filter Query Language

The value of the filter query parameter is an expression involving the fields of the resource that produces a Boolean value. This expression is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response. https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#filter

notes

Advanced Encryption Standard

The Advanced Encryption Standard (AES) is a specification for how electronic data should be encrypted that was published by the National Insitute for Standards in Technology (NIST) in the U.S. in 2001 https://www.thoughtworks.com/insights/blog/privacy/illustrated-guide-advanced-encryption-standard?utm_medium=email&utm_source=marketo&mkt_tok=MTk5LVFERS0yOTEAAAGTfWHXbMeay5dEA78XJDcrELbG96ewhrXEctQc2eHKwAZXhDiPTQAc3VfKce7JKG_WxHuTk8JSwgDCi3K26nb3Zo9UfC7qi7F7eGy_k_KMJVVombQ

speaking

[Conf] Wetest Athens - Testing Openapi Definitions for Better and Consistent Apis

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

notes

API Design Guidelines Impact

A list of key finding to illustrate the impact of AIP Guidelines in the areas of API consumption and API production: API Production: Increased Requirement Fulfillment: A controlled developer experiment showed that developers using API Improvement Proposals (AIPs) and an API linter achieved a 10% higher requirement fulfillment rate compared to those without any protocols. Feedback Utility: Among developers using the linter tool alongside AIPs, 75% found it beneficial, aiding significantly in refining their API designs.

notes

API Designer role

The role of API Designer can evolve from Product Design or Architecture. API Designers should understand Product, UX, DX, technical and architectural constraints. https://brunopedro.com

notes

Idempotency

An idempotent POST is a concept, useful in payment API scenarios. The API provider wants to ensure that if an API call to make a payment fails during execution – such as in timeout scenarios where no discernable HTTP response is returned to the client – subsequent attempts do not result in a duplicate payment instruction submitted. Idempotency is achieved by requiring the client to submit the same instruction with an identifier that signals to the API provider that they might have seen this instruction before.

notes

Werner Vogel's API rules

APIs are Forever When a social media post graces the internet, it leaves a permanent impression on web users thereafter — that’s to say, it remains visible and “on the record” until the end of days. A similar thing happens with AWS’ APIs, though those outcomes are more intentional. When AWS introduces an API, Vogels believes that this API must remain ever-present and largely unchanged. Once companies fundamentally change or remove a longstanding API from general availability, business customers who’ve built atop it will suffer.

notes

JSON merge patch plus and minus

Strengths of JSON Merge Patch: Easy for users to understand and implement. Naturally idempotent Well-defined semantics Robust to versioning Shortcomings of JSON Merge Patch Cumbersome to modify array values

notes

Api Design Specification

What is an API design specification? A collection of patterns (with examples) Rules about how to apply them Tests to automate compliance

notes

Orthogonality in API design

An important quality of API design is minimalism, also called #orthogonality. This is a quality shared with programming language design as well. Adding new terms or concepts complicates the design. It adds rules, exceptions, and quirks, thus making it harder to learn. An example is the famous “verb in the resource name” dilemma.

posts

7 Steps to Review an Api Design

Lay out the Context An API does not live in isolation. It is part of business, involves people, and may sit next to other APIs. All these are necessary to scope and design the API. Instead of that, you could create many integration pipes. It would be difficult to understand them all in a few years. Input: Interviews, relevant api designs, business & architecture diagrams, engineering docs. Identify the nonfunctional requirements Review the security model & performance expectations.

posts

A guide to creating your API design guidelines

For the last year, I have been working on what “better API design” means. How can we better design the public and our internal APIs? The term that comes to my mind to define this is maturity, thus API design maturity. What is API design maturity, then? When I searched on Google, most of the results were about the Richardson Maturity Model. Some results may refer to API-First and how an organization generally treats APIs.

Tag: apis

notes

Load Testing API Challenges

The major pains when setting up load testing APIs are: Create load from multiple client nodes (distributed) that all follow the plan in sync Connect with internal / non-public APIs

notes

AI Automation via APIs

AI is automation. As a result, the best way to offer an ai-powered service is via an API to support automated tasks.

notes

API Documentation and Lifecycle

API documentation can be so much more than API documentation. [It] can be the thread connecting all the stages of the API consumer lifecycle. https://notes.brunopedro.com/2024/06/27/20240627230846/

speaking

[Conf] Wetest Athens - Testing Openapi Definitions for Better and Consistent Apis

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

notes

API Design Guidelines Impact

A list of key finding to illustrate the impact of AIP Guidelines in the areas of API consumption and API production: API Production: Increased Requirement Fulfillment: A controlled developer experiment showed that developers using API Improvement Proposals (AIPs) and an API linter achieved a 10% higher requirement fulfillment rate compared to those without any protocols. Feedback Utility: Among developers using the linter tool alongside AIPs, 75% found it beneficial, aiding significantly in refining their API designs.

notes

API Usability Challenges

Challenges in API usability, as highlighted by Scaffidi [18] and [16], include inadequate documentation, insufficient orthogonality, and mismatches between API abstractions and application requirements. https://dl.acm.org/doi/10.1145/3613905.3650803

notes

API Designer role

The role of API Designer can evolve from Product Design or Architecture. API Designers should understand Product, UX, DX, technical and architectural constraints. https://brunopedro.com

notes

Integration tools

When you buy integration tools, you are agreeing to build the actual integration itself. What you are buying is a promise that the integration can be solved more efficiently and more simply than using a general purpose language

notes

Idempotency

An idempotent POST is a concept, useful in payment API scenarios. The API provider wants to ensure that if an API call to make a payment fails during execution – such as in timeout scenarios where no discernable HTTP response is returned to the client – subsequent attempts do not result in a duplicate payment instruction submitted. Idempotency is achieved by requiring the client to submit the same instruction with an identifier that signals to the API provider that they might have seen this instruction before.

notes

Werner Vogel's API rules

APIs are Forever When a social media post graces the internet, it leaves a permanent impression on web users thereafter — that’s to say, it remains visible and “on the record” until the end of days. A similar thing happens with AWS’ APIs, though those outcomes are more intentional. When AWS introduces an API, Vogels believes that this API must remain ever-present and largely unchanged. Once companies fundamentally change or remove a longstanding API from general availability, business customers who’ve built atop it will suffer.

notes

Contract testing

I had a conversation recently involving contract testing between partners. The provider provides the contract during their ci/cd process before the deployment. The consumer will validate it and if something fails, the change is rejected and the deployment never occurs. The concept of consumers signing off and blocking deployments is very interesting as it empowers and handles the control to the consumer.

speaking

[Podcast] Fireside With Voxgig

https://www.voxgig.com/podcast/episode-170-christos-gkoros-repeat-api-designer-at-postman Who said building robust, production grade APIs had to be hard? As we hope for all technology, the creation and design of APIs has only become easier and more accessible over time. This is due in part to today’s wonderful guest, Christos Gkoros, and his work at Postman as an API designer. Christos comes from a software engineering background and he speaks to us about his journey to his current role.

notes

JSON merge patch plus and minus

Strengths of JSON Merge Patch: Easy for users to understand and implement. Naturally idempotent Well-defined semantics Robust to versioning Shortcomings of JSON Merge Patch Cumbersome to modify array values

notes

Graphql Field Usage

GraphQL has an advantage over simple Web APIs, as it offers some insight into how many users are using each field of your API. Although this insight may not be completely accurate, it can still be useful in estimating the cost of making a breaking change in a specific field. With this information, you can communicate the potential impact of the change more effectively.

notes

Api Design Specification

What is an API design specification? A collection of patterns (with examples) Rules about how to apply them Tests to automate compliance

speaking

[Meetup] Kubernetes Athens - Kubernetes Api Highlight Orchestrating a Flow

https://noti.st/christosgkoros/Agx6Fh/kubernetes-api-highlight-orchestrating-a-flow This presentation explores the power of Kubernetes REST API in managing and orchestrating complex workflows within a Kubernetes cluster. We will dive into a practical use case of provisioning resources, demonstrating how to effectively leverage the Kubernetes REST API for this purpose. The session will include hands-on examples using Postman to interact with the Kubernetes API and making API calls to manage cluster resources. Additionally, we will introduce Postman Flows, a feature within Postman that allows for the orchestration of a sequence of API requests.

posts

Why I Am Starting An Api Meetup

From building APIs I was always intrigued by APIs. Initially, I enjoyed building them. APIs of all kinds; functions, objects, Java interfaces, libraries, and of course, Web APIs. There’s something magical about encapsulating complex information and processes into a single interaction. To the business behind them I fell in love with APIs when I recognized their business significance. Giants like AWS, Twilio, and Stripe have leveraged APIs to build robust, scalable businesses.

notes

Orthogonality in API design

An important quality of API design is minimalism, also called #orthogonality. This is a quality shared with programming language design as well. Adding new terms or concepts complicates the design. It adds rules, exceptions, and quirks, thus making it harder to learn. An example is the famous “verb in the resource name” dilemma.

notes

Deciding on abbreviations and acronyms

Our rule of thumb we settled on in our practice was to do a Google search. If either the abbreviation or acronym for the concept appeared “top of the fold”, we agreed that it was common parlance. Source

posts

7 Steps to Review an Api Design

Lay out the Context An API does not live in isolation. It is part of business, involves people, and may sit next to other APIs. All these are necessary to scope and design the API. Instead of that, you could create many integration pipes. It would be difficult to understand them all in a few years. Input: Interviews, relevant api designs, business & architecture diagrams, engineering docs. Identify the nonfunctional requirements Review the security model & performance expectations.

posts

A guide to creating your API design guidelines

For the last year, I have been working on what “better API design” means. How can we better design the public and our internal APIs? The term that comes to my mind to define this is maturity, thus API design maturity. What is API design maturity, then? When I searched on Google, most of the results were about the Richardson Maturity Model. Some results may refer to API-First and how an organization generally treats APIs.

Tag: load-testing

notes

Load Testing API Challenges

The major pains when setting up load testing APIs are: Create load from multiple client nodes (distributed) that all follow the plan in sync Connect with internal / non-public APIs

Tag: testing

notes

Load Testing API Challenges

The major pains when setting up load testing APIs are: Create load from multiple client nodes (distributed) that all follow the plan in sync Connect with internal / non-public APIs

notes

Contract testing

I had a conversation recently involving contract testing between partners. The provider provides the contract during their ci/cd process before the deployment. The consumer will validate it and if something fails, the change is rejected and the deployment never occurs. The concept of consumers signing off and blocking deployments is very interesting as it empowers and handles the control to the consumer.

Tag: writing

notes

Writing for Thought vs Audience

The text you write for thinking should differ from the text you write for others to read.

Tag: architecture

notes

Architecture Organization Model

Architecture organizing model https://architectelevator.com/architecture/organizing-architecture/

notes

Integration tools

When you buy integration tools, you are agreeing to build the actual integration itself. What you are buying is a promise that the integration can be solved more efficiently and more simply than using a general purpose language

notes

Werner Vogel's API rules

APIs are Forever When a social media post graces the internet, it leaves a permanent impression on web users thereafter — that’s to say, it remains visible and “on the record” until the end of days. A similar thing happens with AWS’ APIs, though those outcomes are more intentional. When AWS introduces an API, Vogels believes that this API must remain ever-present and largely unchanged. Once companies fundamentally change or remove a longstanding API from general availability, business customers who’ve built atop it will suffer.

notes

Gall's law

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched to make it work. You have to start over with a simple working system.

notes

30 system design concepts

Use autoscaling for traffic spikes design for scalability from the start plan for and implement fault tolerance prioritize horizontal scaling for scalability implement data partitioning and sharding use data lakes for analytics and reporting employ CDNs for global latency reduction make operations idempotent for simplicity use event-driven architecture for flexibility employ blob/object storage for media files embrace tradeoffs; perfection is unattainable implement Data Replication and Redundancy Implement rate Limiting for system protection use a read-through cache for read-heavy apps utilize write-through cache for write-heavy apps opt for NoSQL Databases for unstructured data use Heartbeat Mechanisms for failure detection adopt WebSockets for real-time communication employ Database Sharding for horizontal scaling clearly define system use cases and constraints consider microservices for flexibility and scalability design for flexibility; expect requirements to evolve utilize Database Indexing for efficient data retrieval understand requirements thoroughly before designing Utilize asynchronous processing for background tasks consider denormalizing databases for read-heavy tasks avoid over-engineering; add functionality only as needed prefer SQL Databases for structured data and transactions use Load Balancers for high availability and traffic distribution consider message queues for asynchronous communication

notes

Nemawashi

Nemawashi (根回し) in Japanese means an informal process of quietly laying the foundation for some proposed change or project, by talking to the people concerned, gathering support and feedback, and so forth Put more effort and time into searching for and involving people who either will have strong opinions about a large decision or will be affected by that large decision The Rule: anyone can make an architectural decision. The Qualifier: before making the decision, the decision-taker must consult two groups: The first is everyone who will be meaningfully affected by the decision.

Tag: teams

notes

Architecture Organization Model

Architecture organizing model https://architectelevator.com/architecture/organizing-architecture/

Tag: ai

notes

AI Automation via APIs

AI is automation. As a result, the best way to offer an ai-powered service is via an API to support automated tasks.

notes

AI and data transformation

AI has made traditional explicit data transformation obsolete

notes

API Design Guidelines Impact

A list of key finding to illustrate the impact of AIP Guidelines in the areas of API consumption and API production: API Production: Increased Requirement Fulfillment: A controlled developer experiment showed that developers using API Improvement Proposals (AIPs) and an API linter achieved a 10% higher requirement fulfillment rate compared to those without any protocols. Feedback Utility: Among developers using the linter tool alongside AIPs, 75% found it beneficial, aiding significantly in refining their API designs.

notes

AI principles

• Be socially beneficial • Avoid creating or reinforcing unfair bias • Be built and tested for safety • Be accountable to people • Incorporate privacy design principles • Uphold high standards of scientific excellence • Be made available for uses that accord with these principles

notes

AI thinking

AI turns right brain thinking into left brain.

speaking

[Podcast] Life of Dev

https://www.youtube.com/watch?v=DuSS18NzjEw&t=96s&ab_channel=SAEAthens I was invited to the Life of Dev podcast and had a relaxed and insightful conversation on the API Designer role, software, AI and more

notes

AI Inverts the Business Model of the Internet

Last week, Reddit filed their S-1 to go public. At least 10% of their revenue - about $60m - comes from selling data to train Large Language Models. Data sales invert the business model of the Internet. Instead of Reddit building product experiences that create good advertising data to earn more on ads, Reddit will launch product experiences that produce more valuable data to feed to LLMs. The LLM vendors should pay more for better data.

Tag: Automation

notes

AI Automation via APIs

AI is automation. As a result, the best way to offer an ai-powered service is via an API to support automated tasks.

Tag: testimonials

services

Solution architecture manager - Groupama

Mr. Gkoros provided valuable guidance to our team, enhancing our API design skills and supporting us in managing our expanding API landscape effectively. His support enabled both Developers and Solution Architects to focus and gain a deeper understanding of designing APIs and establishing a strong governance model. Solution architecture manager - Groupama

Tag: product

notes

Promotion-Driven User Insights

My favorite question to ask about any user/buyer is, “How does this person get their next promotion? https://www.linkedin.com/posts/jean-yang-96575030_when-i-first-started-akita-i-got-a-lot-of-activity-7257130808891564033-Vcbu?utm_source=share&utm_medium=member_desktop

Tag: sales

notes

Promotion-Driven User Insights

My favorite question to ask about any user/buyer is, “How does this person get their next promotion? https://www.linkedin.com/posts/jean-yang-96575030_when-i-first-started-akita-i-got-a-lot-of-activity-7257130808891564033-Vcbu?utm_source=share&utm_medium=member_desktop

Tag: user-research

notes

Promotion-Driven User Insights

My favorite question to ask about any user/buyer is, “How does this person get their next promotion? https://www.linkedin.com/posts/jean-yang-96575030_when-i-first-started-akita-i-got-a-lot-of-activity-7257130808891564033-Vcbu?utm_source=share&utm_medium=member_desktop

Tag: data

notes

AI and data transformation

AI has made traditional explicit data transformation obsolete

Tag: technology

notes

AI and data transformation

AI has made traditional explicit data transformation obsolete

notes

Technology Trends Cycle

Technology trends ebb and flow between generalization and specialization, consolidation and separation, commoditization and innovation. Each time this happens, we level-up. It’s good business to know where you are in the cycle so you can effectively capitalize on the opportunity and contribute something grand. https://www.linkedin.com/posts/kevinswiber_technology-trends-ebb-and-flow-between-generalization-activity-7249987004782817282-813Z?utm_source=share&utm_medium=member_android

Tag: transformation

notes

AI and data transformation

AI has made traditional explicit data transformation obsolete

Tag: business

notes

Technology Trends Cycle

Technology trends ebb and flow between generalization and specialization, consolidation and separation, commoditization and innovation. Each time this happens, we level-up. It’s good business to know where you are in the cycle so you can effectively capitalize on the opportunity and contribute something grand. https://www.linkedin.com/posts/kevinswiber_technology-trends-ebb-and-flow-between-generalization-activity-7249987004782817282-813Z?utm_source=share&utm_medium=member_android

notes

APi documentation business value

The angle from which to look at the business value of API documentation is the “platform.” When building it, APIs are the core ingredient and the area where different teams interact. Poor documentation affects cross-team collaboration, impacting integration times and incident response. It hinders efforts to achieve predictable, fast delivery and efficient operations. This ultimately affects the teams' ability to reach those business goals and costs $$$. This issue will likely surface in organization-wide surveys.

notes

Disruption

If you are unwilling to disrupt your business, there will always be someone willing to do it for you.

notes

AI Inverts the Business Model of the Internet

Last week, Reddit filed their S-1 to go public. At least 10% of their revenue - about $60m - comes from selling data to train Large Language Models. Data sales invert the business model of the Internet. Instead of Reddit building product experiences that create good advertising data to earn more on ads, Reddit will launch product experiences that produce more valuable data to feed to LLMs. The LLM vendors should pay more for better data.

Tag: innovation

notes

Technology Trends Cycle

Technology trends ebb and flow between generalization and specialization, consolidation and separation, commoditization and innovation. Each time this happens, we level-up. It’s good business to know where you are in the cycle so you can effectively capitalize on the opportunity and contribute something grand. https://www.linkedin.com/posts/kevinswiber_technology-trends-ebb-and-flow-between-generalization-activity-7249987004782817282-813Z?utm_source=share&utm_medium=member_android

notes

The Strategy Tax

The problem that big, established companies get into is what is referred to as the strategy tax. This is basically the fact that they have to sort of fit their next big thing into their existing agenda. And they often compromise in the process.

Tag: trends

notes

Technology Trends Cycle

Technology trends ebb and flow between generalization and specialization, consolidation and separation, commoditization and innovation. Each time this happens, we level-up. It’s good business to know where you are in the cycle so you can effectively capitalize on the opportunity and contribute something grand. https://www.linkedin.com/posts/kevinswiber_technology-trends-ebb-and-flow-between-generalization-activity-7249987004782817282-813Z?utm_source=share&utm_medium=member_android

Tag: humor

notes

SDK development

The two best days in an SDK owner’s life are the day they release it and the day they archive it.

Tag: SDK

notes

SDK development

The two best days in an SDK owner’s life are the day they release it and the day they archive it.

Tag: software-development

notes

SDK development

The two best days in an SDK owner’s life are the day they release it and the day they archive it.

notes

Team Unity Through Shipping

What bonds a team together is shipping software that is used

Tag: api-documentation

notes

APi documentation business value

The angle from which to look at the business value of API documentation is the “platform.” When building it, APIs are the core ingredient and the area where different teams interact. Poor documentation affects cross-team collaboration, impacting integration times and incident response. It hinders efforts to achieve predictable, fast delivery and efficient operations. This ultimately affects the teams' ability to reach those business goals and costs $$$. This issue will likely surface in organization-wide surveys.

notes

API Documentation and Lifecycle

API documentation can be so much more than API documentation. [It] can be the thread connecting all the stages of the API consumer lifecycle. https://notes.brunopedro.com/2024/06/27/20240627230846/

notes

API Usability Challenges

Challenges in API usability, as highlighted by Scaffidi [18] and [16], include inadequate documentation, insufficient orthogonality, and mismatches between API abstractions and application requirements. https://dl.acm.org/doi/10.1145/3613905.3650803

notes

Self Service Api Integration

Given the right documentation, self-service API integration should come naturally, right? What is the proper documentation though and who defines that? Working with teams to reduce the problem to a “set of questions” that the docs must answer, can help you move towards self-service.

Tag: collaboration

notes

APi documentation business value

The angle from which to look at the business value of API documentation is the “platform.” When building it, APIs are the core ingredient and the area where different teams interact. Poor documentation affects cross-team collaboration, impacting integration times and incident response. It hinders efforts to achieve predictable, fast delivery and efficient operations. This ultimately affects the teams' ability to reach those business goals and costs $$$. This issue will likely surface in organization-wide surveys.

Tag: product-delivery

notes

Team Unity Through Shipping

What bonds a team together is shipping software that is used

Tag: teamwork

notes

Team Unity Through Shipping

What bonds a team together is shipping software that is used

notes

Team initiatives

Setup a rotation Invite one person of the team to lead the initiative each time

notes

Prime directive

Engineers, although they may have better ideas or insights, their communication style generates resentment that will limit how much impact they can have in the future. Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.

Tag: Analysis

notes

Polarity map

https://matthewreinbold.com/2021/11/01/PolarityMappingAndAPIGovernance

Tag: strategy

notes

Polarity map

https://matthewreinbold.com/2021/11/01/PolarityMappingAndAPIGovernance

notes

Three Lenses to look at a problem strategically

Lens 1: The person In what ways (if any) might the individual be contributing to the problem? (Things like their workstyle, lack of skill, motivation, clarity.) Lens 2: You In what ways (if any) might you be contributing to the problem? (Maybe you didn’t provide feedback, didn’t set clear expectations.) Lens 3: The team/ organisation In what ways (if any) might the team/organisation/systems be contributing to the problem? (Things like interdependencies, unclear processes, conflicting priorities.

notes

Common Strategy Mistakes

Common mistakes that teams make when not thinking strategically: Focusing on the wrong priorities Focusing on the wrong outcome Not involving the right people at the right time Not seeing the bigger picture Not anticipating problems Not understanding how one project impacts another Working without thinking through why the work is being done Diving into work without thinking if it’s already been solved before Working and getting feedback only at completion (not earlier) Not converting ideas into action in efficient ways

notes

Bad Strategy

Bad strategy ignores the power of choice and focus, trying instead to accommodate a multitude of conflicting demands and interests. Like a quarterback whose only advice to his teammates is “Let’s win,” bad strategy covers up its failure to guide by embracing the language of broad goals, ambition, vision, and values. As seen in: https://www.mckinsey.com/capabilities/strategy-and-corporate-finance/our-insights/the-perils-of-bad-strategy

Tag: psychology

notes

Nostalgia for the past

We tend to say that people were happier in the past because life was simpler. Do you agree with this view? It is an idealization of the past as we ignore the testimonies and experiences of the misery that plagued people. If we turn to classical literature, we will find that the past is much darker than the present. On the other hand, the present has such bright lights that it often causes vertigo.

Tag: interview

notes

What to ask a hiring manager

My favorite question to ask hiring managers, “Can you tell me about someone you have promoted in recent years?”. https://x.com/1sprintatatime/status/1820909764752372191?t=ke7vyfHAFSvCrZ48sO_Brg&s=19

Tag: query-languages

notes

Filter Query Language

The value of the filter query parameter is an expression involving the fields of the resource that produces a Boolean value. This expression is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response. https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#filter

Tag: api-lifecycle

notes

API Documentation and Lifecycle

API documentation can be so much more than API documentation. [It] can be the thread connecting all the stages of the API consumer lifecycle. https://notes.brunopedro.com/2024/06/27/20240627230846/

Tag: api-governance

speaking

[Conf] Wetest Athens - Testing Openapi Definitions for Better and Consistent Apis

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

posts

7 Steps to Review an Api Design

Lay out the Context An API does not live in isolation. It is part of business, involves people, and may sit next to other APIs. All these are necessary to scope and design the API. Instead of that, you could create many integration pipes. It would be difficult to understand them all in a few years. Input: Interviews, relevant api designs, business & architecture diagrams, engineering docs. Identify the nonfunctional requirements Review the security model & performance expectations.

posts

A guide to creating your API design guidelines

For the last year, I have been working on what “better API design” means. How can we better design the public and our internal APIs? The term that comes to my mind to define this is maturity, thus API design maturity. What is API design maturity, then? When I searched on Google, most of the results were about the Richardson Maturity Model. Some results may refer to API-First and how an organization generally treats APIs.

Tag: openapi

speaking

[Conf] Wetest Athens - Testing Openapi Definitions for Better and Consistent Apis

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

posts

OpenAPI to gRPC with Quarkus

Introduction REST (OpenAPI) and gRPC are two of the most popular formats for APIs. REST is the style of choice of most public APIs, and gRPC is a popular alternative for internal APIs that need an efficient network. The OpenAPI Specification defines a standard to describe REST APIs and their capabilities. By default, gRPC uses Protocol Buffers, Google’s open-source mechanism for serializing structured data. The Protocol buffer schema is also an API specification.

Tag: platform-engineering

speaking

[Conf] Wetest Athens - Testing Openapi Definitions for Better and Consistent Apis

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

Tag: speaking

speaking

[Conf] Wetest Athens - Testing Openapi Definitions for Better and Consistent Apis

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

speaking

[Podcast] Life of Dev

https://www.youtube.com/watch?v=DuSS18NzjEw&t=96s&ab_channel=SAEAthens I was invited to the Life of Dev podcast and had a relaxed and insightful conversation on the API Designer role, software, AI and more

speaking

[Podcast] Fireside With Voxgig

https://www.voxgig.com/podcast/episode-170-christos-gkoros-repeat-api-designer-at-postman Who said building robust, production grade APIs had to be hard? As we hope for all technology, the creation and design of APIs has only become easier and more accessible over time. This is due in part to today’s wonderful guest, Christos Gkoros, and his work at Postman as an API designer. Christos comes from a software engineering background and he speaks to us about his journey to his current role.

speaking

[Meetup] Kubernetes Athens - Kubernetes Api Highlight Orchestrating a Flow

https://noti.st/christosgkoros/Agx6Fh/kubernetes-api-highlight-orchestrating-a-flow This presentation explores the power of Kubernetes REST API in managing and orchestrating complex workflows within a Kubernetes cluster. We will dive into a practical use case of provisioning resources, demonstrating how to effectively leverage the Kubernetes REST API for this purpose. The session will include hands-on examples using Postman to interact with the Kubernetes API and making API calls to manage cluster resources. Additionally, we will introduce Postman Flows, a feature within Postman that allows for the orchestration of a sequence of API requests.

Tag: spectral

speaking

[Conf] Wetest Athens - Testing Openapi Definitions for Better and Consistent Apis

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

Tag: developer-tools

notes

API Design Guidelines Impact

A list of key finding to illustrate the impact of AIP Guidelines in the areas of API consumption and API production: API Production: Increased Requirement Fulfillment: A controlled developer experiment showed that developers using API Improvement Proposals (AIPs) and an API linter achieved a 10% higher requirement fulfillment rate compared to those without any protocols. Feedback Utility: Among developers using the linter tool alongside AIPs, 75% found it beneficial, aiding significantly in refining their API designs.

notes

Developer Tools

The core conflict of developer tools is Abstraction vs. complexity Jean Young https://future.com/the-case-for-developer-experience/

Tag: api-usability

notes

API Usability Challenges

Challenges in API usability, as highlighted by Scaffidi [18] and [16], include inadequate documentation, insufficient orthogonality, and mismatches between API abstractions and application requirements. https://dl.acm.org/doi/10.1145/3613905.3650803

Tag: benchmarking

notes

Benchmarking

During benchmarking, pay attention to the outliers. Measure P99 of everything. The average is not meaningful.

Tag: performance

notes

Benchmarking

During benchmarking, pay attention to the outliers. Measure P99 of everything. The average is not meaningful.

Tag: motivation

notes

Comfort and dependency

If things come easy and you get comfortable, you are getting trapped into dependency.

Tag: governance

notes

Tech Governance

Ensure that making the right thing is easy, and the wrong thing, hard.

Tag: change-management

notes

Cultural Change

If you’re trying to make a cultural change, I’ve found it’s much easier to reinforce desired behaviours than to focus on feedback on undesirable behaviours.

notes

Gall's law

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched to make it work. You have to start over with a simple working system.

notes

Fear of change

It is much easier to imagine negative consequences than the positive possibilities of a change. Humans are wired to first think about the risks as a survival trait.

Tag: project-management

notes

Effective Estimations

Estimations are useful in high level discussions about feasibility and underlying technical complexities (like, is this a week or a month, and why?), and also to be able to make trade-offs between quick wins and larger investments. But estimating down to the story point or man-hour is a huge waste of everyone’s time and sanity.

notes

Heilmeier Catechism

What are you trying to do? Articulate your objectives using absolutely no jargon. How is it done today, and what are the limits of current practice? What is new in your approach, and why do you think it will be successful? Who cares? If you are successful, what difference will it make? What are the risks? How much will it cost? How long will it take? What are the mid-term and final “exams” to check for success?

notes

Project management and execution

I prefer not to manage the plan of a project in which I am also responsible for the content and the execution. This is a conflict in responsibilities. F.e. both project manager and solution architect.

Tag: customer

notes

Customer complaints

When a customer brings a complaint, there are always two tokens on the table: “It’s no big deal” and “It’s the end of the world”. Both tokens are always played, so whoever chooses first forces the other to grab the token that’s left. Don’t force your customer into taking the “It’s the end of the world” one. https://brunopedro.com/

Tag: service

notes

Customer complaints

When a customer brings a complaint, there are always two tokens on the table: “It’s no big deal” and “It’s the end of the world”. Both tokens are always played, so whoever chooses first forces the other to grab the token that’s left. Don’t force your customer into taking the “It’s the end of the world” one. https://brunopedro.com/

Tag: ownership

notes

Ownership in Tech

In all cases, you should push decisions as far down your org chart as they can go. Consider how much pain and inefficiency you’re willing to take, in exchange for people feeling ownership over their goals and mission. I’d enjoy dictating exactly how our new dashboard should operate, but it’s in our organization’s best interest to let the dashboard team make those decisions. If I dictate their work, they’ll execute on it.

Tag: software

speaking

[Podcast] Life of Dev

https://www.youtube.com/watch?v=DuSS18NzjEw&t=96s&ab_channel=SAEAthens I was invited to the Life of Dev podcast and had a relaxed and insightful conversation on the API Designer role, software, AI and more

speaking

[Podcast] Fireside With Voxgig

https://www.voxgig.com/podcast/episode-170-christos-gkoros-repeat-api-designer-at-postman Who said building robust, production grade APIs had to be hard? As we hope for all technology, the creation and design of APIs has only become easier and more accessible over time. This is due in part to today’s wonderful guest, Christos Gkoros, and his work at Postman as an API designer. Christos comes from a software engineering background and he speaks to us about his journey to his current role.

notes

Software Documentation

Don’t document the obvious: I see too many documents that contain sentences like “Name field - contains the name”. Tell me about what I may not know - restrictions on characters, how these are sorted, what if someone doesn’t have a first name, etc. Gregor Hohpe

notes

Software perspectives

There are three perspectives in software development that are not well aligned: academia, thought-leaders/influencers and the work being done in practice. Jean Young

notes

Rule of three

Every programmer ever born thinks whatever idea just popped out of their head into their editor is the most generalized, most flexible, most one-size-fits all solution that has ever been conceived. We think we’ve built software that is a general purpose solution to some set of problems, but we are almost always wrong. It is three times as difficult to build reusable components as single use components, and a reusable component should be tried out in three different applications before it will be sufficiently general to accept into a reuse library.

Tag: quotes

notes

Creator mode

When you don’t create things, you become defined by your tastes rather than ability. Your tastes only narrow & exclude people. So create.

notes

Feyman technique

If you can’t explain a solution, then you don’t really understand it.

notes

10k hours expert

8h per day for 3.5 years make you an expert 4h per day for 7 years make you an expert 1h per day for 28 years makes you an expert

notes

Chesterton's fence

Chesterton’s fence is the principle that reforms should not be made until the reasoning behind the existing state of affairs is understood.

notes

Tragedy of the commons

In economic science, the tragedy of the commons is a situation in which individual users, who have open access to a resource unhampered by shared social structures or formal rules that govern access and use, act independently according to their own self-interest and, contrary to the common good of all users, cause depletion of the resource through their uncoordinated action.

notes

Rest and Definitions

REST means different things to different audiences. It means one thing to the developer completing their assignments in Jira, another to the engineering leader attempting to herd cats through a transformation, and yet another to the marketplace selling solutions. The term’s conflation isn’t an indictment of people’s laxness but an example of its success. We see this pattern repeatedly throughout the tech landscape. Agile methodologies, cloud computing, and even DevOps all started with specific principles but branched out, sometimes to their originator’s chagrin, as diverse groups adopted them.

notes

Soft vs Hard Skills

Soft skills dominate hard skills. Many hard skills will be automated by AI anyway. Soft skills and human relationships are the future, and emotional intelligence can be learned.

notes

Shirky Principle

The Shirky principle is the adage that “institutions will try to preserve the problem to which they are the solution”. More broadly, it can also be characterized as the adage that “every entity tends to prolong the problem it is solving”.

notes

Developer Tools

The core conflict of developer tools is Abstraction vs. complexity Jean Young https://future.com/the-case-for-developer-experience/

notes

Self Service Api Integration

Given the right documentation, self-service API integration should come naturally, right? What is the proper documentation though and who defines that? Working with teams to reduce the problem to a “set of questions” that the docs must answer, can help you move towards self-service.

notes

Creativity

Creativity comes from constraint.

Tag: api-management

notes

Integration tools

When you buy integration tools, you are agreeing to build the actual integration itself. What you are buying is a promise that the integration can be solved more efficiently and more simply than using a general purpose language

Tag: integration

notes

Integration tools

When you buy integration tools, you are agreeing to build the actual integration itself. What you are buying is a promise that the integration can be solved more efficiently and more simply than using a general purpose language

Tag: system-design

notes

Gall's law

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched to make it work. You have to start over with a simple working system.

notes

30 system design concepts

Use autoscaling for traffic spikes design for scalability from the start plan for and implement fault tolerance prioritize horizontal scaling for scalability implement data partitioning and sharding use data lakes for analytics and reporting employ CDNs for global latency reduction make operations idempotent for simplicity use event-driven architecture for flexibility employ blob/object storage for media files embrace tradeoffs; perfection is unattainable implement Data Replication and Redundancy Implement rate Limiting for system protection use a read-through cache for read-heavy apps utilize write-through cache for write-heavy apps opt for NoSQL Databases for unstructured data use Heartbeat Mechanisms for failure detection adopt WebSockets for real-time communication employ Database Sharding for horizontal scaling clearly define system use cases and constraints consider microservices for flexibility and scalability design for flexibility; expect requirements to evolve utilize Database Indexing for efficient data retrieval understand requirements thoroughly before designing Utilize asynchronous processing for background tasks consider denormalizing databases for read-heavy tasks avoid over-engineering; add functionality only as needed prefer SQL Databases for structured data and transactions use Load Balancers for high availability and traffic distribution consider message queues for asynchronous communication

Tag: contract-testing

notes

Contract testing

I had a conversation recently involving contract testing between partners. The provider provides the contract during their ci/cd process before the deployment. The consumer will validate it and if something fails, the change is rejected and the deployment never occurs. The concept of consumers signing off and blocking deployments is very interesting as it empowers and handles the control to the consumer.

Tag: leading change

notes

Nemawashi

Nemawashi (根回し) in Japanese means an informal process of quietly laying the foundation for some proposed change or project, by talking to the people concerned, gathering support and feedback, and so forth Put more effort and time into searching for and involving people who either will have strong opinions about a large decision or will be affected by that large decision The Rule: anyone can make an architectural decision. The Qualifier: before making the decision, the decision-taker must consult two groups: The first is everyone who will be meaningfully affected by the decision.

Tag: devops

notes

Observability

Observability without action is just storage Too many people store terabytes of data and call it observability https://twitter.com/boristane/status/1783842355147325494?t=5OUgcOmHIcwbGqrdIjR1Hw&s=19

Tag: observability

notes

Observability

Observability without action is just storage Too many people store terabytes of data and call it observability https://twitter.com/boristane/status/1783842355147325494?t=5OUgcOmHIcwbGqrdIjR1Hw&s=19

Tag: devrel

speaking

[Podcast] Fireside With Voxgig

https://www.voxgig.com/podcast/episode-170-christos-gkoros-repeat-api-designer-at-postman Who said building robust, production grade APIs had to be hard? As we hope for all technology, the creation and design of APIs has only become easier and more accessible over time. This is due in part to today’s wonderful guest, Christos Gkoros, and his work at Postman as an API designer. Christos comes from a software engineering background and he speaks to us about his journey to his current role.

Tag: meetups

speaking

[Podcast] Fireside With Voxgig

https://www.voxgig.com/podcast/episode-170-christos-gkoros-repeat-api-designer-at-postman Who said building robust, production grade APIs had to be hard? As we hope for all technology, the creation and design of APIs has only become easier and more accessible over time. This is due in part to today’s wonderful guest, Christos Gkoros, and his work at Postman as an API designer. Christos comes from a software engineering background and he speaks to us about his journey to his current role.

Tag: rest

notes

Rest and Definitions

REST means different things to different audiences. It means one thing to the developer completing their assignments in Jira, another to the engineering leader attempting to herd cats through a transformation, and yet another to the marketplace selling solutions. The term’s conflation isn’t an indictment of people’s laxness but an example of its success. We see this pattern repeatedly throughout the tech landscape. Agile methodologies, cloud computing, and even DevOps all started with specific principles but branched out, sometimes to their originator’s chagrin, as diverse groups adopted them.

Tag: api-as-a-product

notes

Graphql Field Usage

GraphQL has an advantage over simple Web APIs, as it offers some insight into how many users are using each field of your API. Although this insight may not be completely accurate, it can still be useful in estimating the cost of making a breaking change in a specific field. With this information, you can communicate the potential impact of the change more effectively.

Tag: graphql

notes

Graphql Field Usage

GraphQL has an advantage over simple Web APIs, as it offers some insight into how many users are using each field of your API. Although this insight may not be completely accurate, it can still be useful in estimating the cost of making a breaking change in a specific field. With this information, you can communicate the potential impact of the change more effectively.

Tag: api-design-specification

notes

Api Design Specification

What is an API design specification? A collection of patterns (with examples) Rules about how to apply them Tests to automate compliance

Tag: kubernetes

speaking

[Meetup] Kubernetes Athens - Kubernetes Api Highlight Orchestrating a Flow

https://noti.st/christosgkoros/Agx6Fh/kubernetes-api-highlight-orchestrating-a-flow This presentation explores the power of Kubernetes REST API in managing and orchestrating complex workflows within a Kubernetes cluster. We will dive into a practical use case of provisioning resources, demonstrating how to effectively leverage the Kubernetes REST API for this purpose. The session will include hands-on examples using Postman to interact with the Kubernetes API and making API calls to manage cluster resources. Additionally, we will introduce Postman Flows, a feature within Postman that allows for the orchestration of a sequence of API requests.

Tag: cli

notes

CLI Design

Great insights @ https://clig.dev/#output like Responsive is more important than fast I have to update the list of areas where interface design applies : APIs Query Languages CLIs

Tag: design

notes

CLI Design

Great insights @ https://clig.dev/#output like Responsive is more important than fast I have to update the list of areas where interface design applies : APIs Query Languages CLIs

Tag: DX

notes

CLI Design

Great insights @ https://clig.dev/#output like Responsive is more important than fast I have to update the list of areas where interface design applies : APIs Query Languages CLIs

Tag: documentation

notes

Software Documentation

Don’t document the obvious: I see too many documents that contain sentences like “Name field - contains the name”. Tell me about what I may not know - restrictions on characters, how these are sorted, what if someone doesn’t have a first name, etc. Gregor Hohpe

Tag: community

posts

Why I Am Starting An Api Meetup

From building APIs I was always intrigued by APIs. Initially, I enjoyed building them. APIs of all kinds; functions, objects, Java interfaces, libraries, and of course, Web APIs. There’s something magical about encapsulating complex information and processes into a single interaction. To the business behind them I fell in love with APIs when I recognized their business significance. Giants like AWS, Twilio, and Stripe have leveraged APIs to build robust, scalable businesses.

Tag: meetup

posts

Why I Am Starting An Api Meetup

From building APIs I was always intrigued by APIs. Initially, I enjoyed building them. APIs of all kinds; functions, objects, Java interfaces, libraries, and of course, Web APIs. There’s something magical about encapsulating complex information and processes into a single interaction. To the business behind them I fell in love with APIs when I recognized their business significance. Giants like AWS, Twilio, and Stripe have leveraged APIs to build robust, scalable businesses.

Tag: api-integration

notes

Self Service Api Integration

Given the right documentation, self-service API integration should come naturally, right? What is the proper documentation though and who defines that? Working with teams to reduce the problem to a “set of questions” that the docs must answer, can help you move towards self-service.

Tag: orthogonality

notes

Orthogonality in API design

An important quality of API design is minimalism, also called #orthogonality. This is a quality shared with programming language design as well. Adding new terms or concepts complicates the design. It adds rules, exceptions, and quirks, thus making it harder to learn. An example is the famous “verb in the resource name” dilemma.

Tag: developer-experience

notes

Abstracting complexity and empowering developers

When balancing between abstracting complexity away and empowering developers, I ask: What’s their goal? How might we reduce the risk of error? What parts of the current experience do developer enjoy the most? What parts are mundane and tedious?

Tag: career

notes

Career strategy

Take on new challenges (risks). As I wrote in a recent post, you break in (get more scope) by having significant high-visibility wins that get leaders to believe you are “great.” Just being competent won’t do it. Better to risk losing big and switch companies if that happens than to stay stuck in the middle.

notes

On power in jobs

The closer you are to the flow of money the more power you have.

Tag: acronyms

notes

Deciding on abbreviations and acronyms

Our rule of thumb we settled on in our practice was to do a Google search. If either the abbreviation or acronym for the concept appeared “top of the fold”, we agreed that it was common parlance. Source

Tag: api-design-review

posts

7 Steps to Review an Api Design

Lay out the Context An API does not live in isolation. It is part of business, involves people, and may sit next to other APIs. All these are necessary to scope and design the API. Instead of that, you could create many integration pipes. It would be difficult to understand them all in a few years. Input: Interviews, relevant api designs, business & architecture diagrams, engineering docs. Identify the nonfunctional requirements Review the security model & performance expectations.

Tag: api-design-guidelines

posts

A guide to creating your API design guidelines

For the last year, I have been working on what “better API design” means. How can we better design the public and our internal APIs? The term that comes to my mind to define this is maturity, thus API design maturity. What is API design maturity, then? When I searched on Google, most of the results were about the Richardson Maturity Model. Some results may refer to API-First and how an organization generally treats APIs.

Tag: metrics

notes

Goodhart Law

Employees are smart enough to know that if a measure is used to evaluate them, then they should optimize that measure. This is captured by Goodhart’s Law: “When a measure becomes a target, it ceases to be a good measure.”

Tag: life

notes

5 rules of 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.

notes

Procrastination

Procrastinators and blockers favor speed and immediacy over accuracy and constancy. 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.

Tag: reusability

notes

Rule of three

Every programmer ever born thinks whatever idea just popped out of their head into their editor is the most generalized, most flexible, most one-size-fits all solution that has ever been conceived. We think we’ve built software that is a general purpose solution to some set of problems, but we are almost always wrong. It is three times as difficult to build reusable components as single use components, and a reusable component should be tried out in three different applications before it will be sufficiently general to accept into a reuse library.

Tag: digital transformation

notes

The Pitch for Enterprise Architecture

Many things in this organization operate in siloes - business functions, business processes, IT applications, infrastructure teams etc - it’s the nature of organizations. However, this can add cost, complexity, and risk because different teams go in different directions, duplicating things or conflicting with each other - IT is not aligned with the business, or the business itself is not aligned. In addition, each team / silo is naturally incented to make decisions that are best for them, but not necessarily best for the org as a whole - who is looking at the overall big picture?

posts

How architectural design review can support digital transformation

Intro Successful digital transformation requires a focus on enterprise architecture, whether improving the system’s or application’s architecture or implementing strategies like API standardization. For an enterprise to practice architecture in an agile environment, several architects and designers must support the project’s agile value streams, which are the actions taken from conception to delivery and support that add value to a product or service. One organization may have a different team of architects producing solution designs and templates.

Tag: enterprise architecture

notes

The Pitch for Enterprise Architecture

Many things in this organization operate in siloes - business functions, business processes, IT applications, infrastructure teams etc - it’s the nature of organizations. However, this can add cost, complexity, and risk because different teams go in different directions, duplicating things or conflicting with each other - IT is not aligned with the business, or the business itself is not aligned. In addition, each team / silo is naturally incented to make decisions that are best for them, but not necessarily best for the org as a whole - who is looking at the overall big picture?

Tag: api-specification-first

posts

OpenAPI to gRPC with Quarkus

Introduction REST (OpenAPI) and gRPC are two of the most popular formats for APIs. REST is the style of choice of most public APIs, and gRPC is a popular alternative for internal APIs that need an efficient network. The OpenAPI Specification defines a standard to describe REST APIs and their capabilities. By default, gRPC uses Protocol Buffers, Google’s open-source mechanism for serializing structured data. The Protocol buffer schema is also an API specification.

Tag: grpc

posts

OpenAPI to gRPC with Quarkus

Introduction REST (OpenAPI) and gRPC are two of the most popular formats for APIs. REST is the style of choice of most public APIs, and gRPC is a popular alternative for internal APIs that need an efficient network. The OpenAPI Specification defines a standard to describe REST APIs and their capabilities. By default, gRPC uses Protocol Buffers, Google’s open-source mechanism for serializing structured data. The Protocol buffer schema is also an API specification.

Tag: quarkus

posts

OpenAPI to gRPC with Quarkus

Introduction REST (OpenAPI) and gRPC are two of the most popular formats for APIs. REST is the style of choice of most public APIs, and gRPC is a popular alternative for internal APIs that need an efficient network. The OpenAPI Specification defines a standard to describe REST APIs and their capabilities. By default, gRPC uses Protocol Buffers, Google’s open-source mechanism for serializing structured data. The Protocol buffer schema is also an API specification.

Tag: adr

posts

How architectural design review can support digital transformation

Intro Successful digital transformation requires a focus on enterprise architecture, whether improving the system’s or application’s architecture or implementing strategies like API standardization. For an enterprise to practice architecture in an agile environment, several architects and designers must support the project’s agile value streams, which are the actions taken from conception to delivery and support that add value to a product or service. One organization may have a different team of architects producing solution designs and templates.

Tag: agile

posts

How architectural design review can support digital transformation

Intro Successful digital transformation requires a focus on enterprise architecture, whether improving the system’s or application’s architecture or implementing strategies like API standardization. For an enterprise to practice architecture in an agile environment, several architects and designers must support the project’s agile value streams, which are the actions taken from conception to delivery and support that add value to a product or service. One organization may have a different team of architects producing solution designs and templates.

Tag: architecture-design-review

posts

How architectural design review can support digital transformation

Intro Successful digital transformation requires a focus on enterprise architecture, whether improving the system’s or application’s architecture or implementing strategies like API standardization. For an enterprise to practice architecture in an agile environment, several architects and designers must support the project’s agile value streams, which are the actions taken from conception to delivery and support that add value to a product or service. One organization may have a different team of architects producing solution designs and templates.