We discuss all things APIs: what makes them great, what makes them bad, and what we might like to see in them while Michael plays a lawyer on channel 46, Allen doesn’t know his favorite part of the show, and Joe definitely pays attention to the tips of the week.

For those reading this episode’s show notes via their podcast player, you can find this episode’s show notes at https://www.codingblocks.net/episode157 where you can be a part of the conversation.

Sponsors

• Datadog –  Sign up today for a free 14 day trial and get a free Datadog t-shirt after creating your first dashboard.

Survey Says

News

• Big thanks to everyone that left us a new review:
  • iTunes: hhskakeidmd
  • Audible: Colum Ferry

All About APIs

What are APIs?

• API stands for application programming interface and is a formal way for applications to speak to each other.
• An API defines requests that you can make, what you need to provide, and what you get back.
• If you do any googling, you’ll see that articles are overwhelmingly focused on Web APIs, particularly REST, but that is far from the only type. Others include:
  • All libraries,
  • All frameworks,
  • System Calls, i.e.: Windows API,
  • Remote API (aka RPC – remote procedure call),
  • Web related standards such as SOAP, REST, HATEOAS, or GraphQL, and
  • Domain Specific Languages (SQL for example)
• The formal definition of APIs, who own them, and what can be done with them is complicated à la Google LLC v. Oracle America, Inc.
• Different types of API have their own set of common problems and best practices
  • Common REST issues:
    • Authentication,
    • Rate limiting,
    • Asynchronous operations,
    • Filtering,
    • Sorting,
    • Pagination,
    • Caching, and
    • Error handling.
  • Game libraries:
    • Heavy emphasis on inheritance and “hidden” systems to cut down on complexity.
  • Libraries for service providers
    • Support multiple languages and paradigms (documentation, versioning, rolling out new features, supporting different languages and frameworks)
• OData provides a set of standards for building and consuming REST API’s.

General tips for writing great APIs

• Make them easy to work with.
• Make them difficult to misuse (good documentation goes a long way).
• Be consistent in the use of terms, input/output types, error messages, etc.
• Simplicity: there’s one way to do things. Introduce abstractions for common actions.
• Service evolution, i.e. including the version number as part of your API call enforces good versioning habits.
• Documentation, documentation, documentation, with enough detail that’s good to ramp up from getting started to in depth detail.
• Platform Independence: try to stay away from specifics of the platforms you expect to deal with.

Why is REST taking over the term API?

• REST is crazy popular in web development and it’s really tough to do anything without it.
• It’s simple. Well, not really if you consider the 43 things you need to think about.
• Some things about REST are great by design, such as:
  • By using it, you only have one protocol to support,
  • It’s verb oriented (commonly used verbs include GET, POST, PUT, PATCH, and DELETE), and
  • It’s based on open standards.
• Some things about REST are great by convention, such as:
  • Noun orientation like resources and identifiers,
  • Human readable I/O,
  • Stateless requests, and
  • HATEOAS provides a methodology to decouple the client and the server.

Maybe we can steal some ideas from REST

• Organize the API around resources, like /orders + verbs instead of /create-order.
  • Note that nouns can be complex, an order can be complex … products, addresses, history, etc.
  • Collections are their own resources (i.e. /orders could return more than 1).
• Consistent naming conventions makes for easy discovery.
• Microsoft recommends plural nouns in most cases, but their skewing heavily towards REST, because REST already has a mechanism for behaviors with their verbs. For example /orders and /orders/123.
  • You can drill in further and further when you orient towards nouns like /orders/123/status.
• The general guidance is to return resource identifiers rather than whole objects for complex nouns. In the order example, it’s better to return a customer ID associated with the whole order.
• Avoid introducing dependencies between the API and the underlying data sources or storage, the interface is meant to abstract those details!
• Verb orientation is okay in some, very action based instances, such as a calculator API.

Resources We Like

• API (Wikipedia)
• The Linux Kernel API (kernel.org)
• gRPC (Wikipedia)
• S3 Compatible API (Backblaze)
• Storing Data Shouldn’t Cost More Than Generating It (Wasabi)
• Top 50 Most Popular APIs on RapidAPI (2021) (rapidapi.com)
• Free Public APIs for Developers APIs (rapidapi.com)
• API Reference (Datadog)
• OData – the best way to REST (odata.org)
• Understand OData in 6 steps (odata.org)
• Best practices for REST API design (Stack Overflow)
• Best Practices in API Design (swagger.io)
• Web API design (docs.microsoft.com)
• The Web API Checklist — 43 Things To Think About When Designing, Testing, and Releasing your API (mathieu.fenniak.net)
• Google API Design Guide (apistylebook.com)
• The DevOps Handbook – Create Organizational Learning (episode 145)
• How to Scrum (episode 156)
• State of JS 2020 (stateofjs.com)

Tip of the Week

• Docker Desktop: WSL 2 Best practices (Docker)
  • Experiencing déjà vu? That’s because we talked about this during episode 156.
• With Minikube, you can easily configure the amount of CPU and RAM each time you start it.
  • Minikube default CPU/Memory (Stack Overflow)
• Listen to American Scandal. A great podcast with amazing production quality. (Wondery)
• If you have a license for DataGrip and use other JetBrains IDEs, once you add a data source, the IDE will recognize strings that are SQL in your code, be they Java, JS, Python, etc., and give syntax highlighting and autocomplete.
  • Also, you can set the connection to a DB in DataGrip as read only under the options. This will give you a warning message if you try a write operation even if your credentials have write permissions.
• API Blueprint. A powerful high-level API description language for web APIs. (apiblueprint.org)
• Apache Superset – A modern data exploration and visualization platform. (Apache)
• Use console.log() like a pro. (markodenic.com)
  • Turns out we did discuss something similar to this back in episode 44.
• Telerik Fiddler – A must have web debugging tool for your web APIs. (Telerik)
• New Docker Build secret information (docs.docker.com)

We discuss the parts of the scrum process that we’re supposed to pay attention to while Allen pronounces the m, Michael doesn’t, and Joe skips the word altogether.

If you’re reading this episode’s show notes via your podcast player, just know that you can find this episode’s show notes at https://www.codingblocks.net/episode156. Stop by, check it out, and join the conversation.

Sponsors

• Datadog –  Sign up today for a free 14 day trial and get a free Datadog t-shirt after creating your first dashboard.

Survey Says

News

• Hey, we finally updated the Resources page. It only took a couple years.
• Apparently we don’t understand the purpose of the scrum during rugby. (Wikipedia)

Standup Time

User Stories

• A user story is a detailed, valuable chunk of work that can be completed in a sprint.\
• Use the INVEST mnemonic created by Bill Wake:
  • I = Independent – the story should be able to be completed without any dependencies on another story
  • N = Negotiable – the story isn’t set in stone – it should have the ability to be modified if needed
  • V = Valuable – the story must deliver value to the stakeholder
  • E = Estimable – you must be able to estimate the story
  • S = Small – you should be able to estimate within a reasonable amount of accuracy and completed within a single sprint
  • T = Testable – the story must have criteria that allow it to be testable

Stories Should be Written in a Format Very Much Like…

“As a _____, I want _____ so that _____.”, like
“As a user, I want MFA in the user profile so I can securely log into my account” for a functional story, or
“As a developer, I want to update our version of Kubernetes so we have better system metrics” for a nonfunctional story.

Stories Must have Acceptance Criteria

• Each story has it’s own UNIQUE acceptance criteria.
• For the MFA story, the acceptance criteria might be:\
  • Token is captured and saved.
  • Verification of code completed successfully.
  • Login works with new MFA.
• The acceptance criteria defines what “done” actually means for the story.

Set up Team Boundaries

• Define “done”.
  • Same requirement for ALL stories:
    • Must be tested in QA environment,
    • Must have test coverage for new methods.
• Backlog prioritization or “grooming”.
  • Must constantly be ordered by value, typically by the project owner.
• Define sprint cadence
  • Usually 1-4 weeks in length, 2-3 is probably best.
  • Two weeks seems to be what most choose simply because it sort of forces a bit of urgency on you.

Estimates

• Actual estimation, “how many hours will a task take?”
• Relative estimation, “I think this task will take 2x as long as this other ticket.”
• SCRUM uses both, user stories are compared to each other in relative fashion.
• By doing it this way, it lets external stakeholders know that it’s an estimate and not a commitment.
• Story points are used to convey relative sizes.
• Estimation is supposed to be lightweight and fast.

Roadmap and Release Plan

• The roadmap shows when themes will be worked on during the timeframe.\
  • You should be able to have a calendar and map your themes across that calendar and in an order that makes sense for getting a functional system.
• Just because you should have completed, functional components at the end of each sprint, based on the user stories, that doesn’t mean you’re releasing that feature to your customer. It may take several sprints before you’ve completed a releasable feature.
• It will take several sprints to find out what a team’s stabilized velocity is, meaning that the team will be able to decently predict how many story points they can complete in a given sprint.

Filling up the Sprint

• Decide how many points you’ll have for a sprint.
• Determine how many sprints before you can release the MVP.
• Fill up the sprints as full as possible in priority order UNLESS the next priority story would overflow the sprint.
  • Simple example, let’s say your sprint will have 10 points and you have the following stories:
    Story A – 3 points
    Story B – 5 points
    Story C – 8 points
    Story D – 2 points
  • Your sprints might look like:
    Sprint 1 – A (3) B(5), D(2) = 10 points
    Sprint 2 – C (8)
  • Story C got bumped to Sprint 2 because the goal is to maximize the amount of work that can be completed in a given sprint in priority order, as much as possible.
• The roadmap is an estimate of when the team will complete the stories and should be updated at the end of each sprint. In other words, the roadmap is a living document.

Sprint Planning

• This is done at the beginning of each sprint.
• Attendees – all developers, scrum master, project owner.
• Project owner should have already prioritized the stories in the backlog.
• The goal of the planning meeting is to ensure all involved understand the stories and acceptance criteria.
  • Also make sure the overarching definition of “done” is posted as a reminder.
• Absolutely plan for a Q&A session.
  • Crucial to make sure any misunderstandings of the stories are cleared here.
• Next the stories are broken down into specific tasks. These tasks are given actual estimates in time.
  • Once this is completed, you need to verify that the team has enough capacity to complete the tasks and stories in the sprint.
    • In general, each team member can only complete 6 hours of actual work per day on average.
• Each person is then asked whether they commit to the work in the sprint.
  • Must give a “yes” or “no” and why.
    • If someone can’t commit with good reason, the the project owner and team need to work together to modify the sprint so that everyone can commit. This is a highly collaborative part of scrum planning.

Stakeholder Feedback

• Information radiators are used to post whatever you think will help inform the stakeholders of the progress, be it a task board or burn down chart.

Task board

• Lists stories committed to in the sprint.
• Shows the status of any current tasks.
• Lists which tasks have been completed.
  • Swimlanes are typically how these are depicted with lanes like: Story, Not Started, In Progress, Completed.

Sprint burndown chart

• Shows ongoing status of how you’re doing with completing the sprint.

Daily Standup

• The purpose of the standup is the three C’s:\
  • Collaboration,
  • Communication, and
  • Cadence.
• The entire team must join: developers, project owner, QA, scrum master.
• Should occur at the same time each day.
• Each status should just be an overview and light on the details.
• Tasks are moved to a new state during the standup, such as from Not Started to In Progress.
• Stakeholders can come to the scrum but should hold questions until the end.
• Cannot go over 15 minutes. It can be shorter, but should not be longer.
• Each person should answer three questions:
  • What did you do yesterday?,
  • What are you doing today?, and
  • Are there any blockers?
• If you see someone hasn’t made progress in several days, this is a great opportunity to ask to help. This is part of keeping the team members accountable for progressing.
• Blockers are brought up during the meeting as anyone on the team needs to try and step in to help. If the issue hasn’t been resolved by the next day, then it’s the responsibility of the scrum master to try and resolve it, and escalate it further up the chain after that, such as to the project owner and so on, each consecutive day.
• Again, very important, this is just the formal way to keep the entire team aware of the progress. People should be communicating throughout the day to complete whatever tasks they’re working on.

Backlog Refinement

• The backlog is constantly changing as the business requirements change.
  • It is the job of the project owner to be in constant communication with the stakeholders to ensure the backlog represents the most important needs of the business and making sure the stories are prioritized in value order.
  • Stories are constantly being modified, added, or removed.
• Around the midpoint of the sprint, there is usually a 30-60 minute “backlog refinement session” where the team comes together to discuss the changes in the backlog.
  • These new stories can only be added to future sprints.
  • The current sprint commitment cannot be changed once the sprint begins.
  • The importance of this mid-sprint session is the team can ask clarifying questions and will be better prepared for the upcoming sprint planning.
    • This helps the project owner know when there are gaps in the requirements and helps to improve the stories.

Marking a Story Done

• The project owner has the final say making sure all the acceptance criteria has been met.
• There could be another meeting called the “sprint review” where the entire team meets to get signoff on the completed stories.
  • Anything not accepted as done gets reviewed, prioritized, and moved out to another sprint.
    • This can happen when a team discovers new information about a story while working on it during a sprint.
  • The team agrees on what was completed and what can be demonstrated to the stakeholders.

The Demo

• This is a direct communication between the team and the stakeholders and receive feedback.
  • This may result in new stories.
  • Stakeholders may not even want the new feature and that’s OK. It’s better to find out early rather than sinking more time into building something not needed or wanted.
• This is a great opportunity to build a relationship between the team members and the stakeholders.
• This demo also shows the overall progress towards the final goal.
• May not be able to demo at the end of every sprint, but you want to do it as often as possible.

Team Retrospective

• Focus is on team performance, not the product and is facilitated by the scrum master.
• This is a closed door session and must be a safe environment for discussion.
  • Only dedicated team members present and the team norms must be observed
• You want an open dialogue/
• What worked well? Focus on good team collaboration.
• What did not work well? Focus on what you can actually change.
• What can be improved?
  • Put items into an improvement backlog
  • Focus on one or two items in the next sprint
• Start with team successes first!

Resources We Like

• Scrum: The Basics (LinkedIn)
• Manifesto for Agile Software Development (agilemanifesto.org)
• Scrum (rugby) (Wikipedia)
• INVEST (mnemonic) (Wikipedia)
• Excellent examples of how not to write user stories (Twitter)
• The Pragmatic Programmer – How to Estimate (episode 109)
• Why is there a 20 and not 21 in some versions of Planning Poker? (Stack Overflow)

Tip of the Week

• Test your YAML with the Ansible Template Tester (ansible.sivel.net)
• Hellscape by Andromida (Spotify, YouTube)
• Use ALT+LEFT CLICK in Windows Terminal to open a new terminal in split screen mode.
• Learn how to tie the correct knot for every situation! (animatedknots.com)
• Apply zoom levels to each tab independently of other tabs of the same website with Per Tab Zoom. (Chrome web store)
• Nearly every page on GitHub has a keyboard shortcut to perform actions faster. Learn them! (GitHub)
• Speaking of shortcuts, here’s a couple for Visual Studio Code:
  • Use CTRL+P (or CMD+P on a Mac) to find a file by name or path.
  • List (and search) all available commands with CTRL+SHIFT+P (or CMD+SHIFT+P on a … you know).
  • Use CTRL+K M (CMD+K M) to change the current document’s language mode.
• Access your WSL2 filesystem from Windows using special network share: like \\wsl$\ubuntu_instance_name\home\your_username\some_path
  • Docker Desktop: WSL 2 Best practices (Docker)