When building great digital products, we need to consider the disciplines of design, engineering, and business simultaneously. And behind every beautiful and usable frontend, there stands, hopefully, a fitting, performant, robust, and maintainable backend. These backends consist of APIs that are sustainable.

This post will outline a few ideas and patterns essential to sustainable API design.

Form

APIs are more than just communication interfaces between systems and machines; they also need to facilitate communication between humans. APIs are often created outside the teams consuming them and thus need to follow the principle of least astonishment (POLA).

People are part of the system. The design should match the user's experience, expectations, and mental models.

Sustainable APIs use the HTTP verbs correctly, has consistent error handling, and, in the spirit of domain-driven design, words mean what they do in the domain. The URLs are human-readable and understandable, even without a client library, helping the front-enders and other consumers to iterate quickly and confidently.

They are also documented in a machine- and human-readable way, utilizing existing ecosystems like OpenAPI, Swagger, and the like. Consumers should be able to quickly consume our APIs using their programming language and tech stack of choice.

Monitoring

Sustainable APIs are not alone; they are monitored. They have a team who care for them, watching their use, performance and availability. APIs need not only to provide the correct response but also to do so timely and consistently. Logging is not enough; the team must act proactively if something is amiss. Consumers or users should never be the ones to alert the team first. The API must tell us itself.

Sustainable APIs don't have outages, but when they do, their status is communicated honestly and understandably to consumers. Sharing information is critical, both to affected consumers and also to others inside our organization. It can be hard to know who needs to know what, so oversharing is caring. And when the problem is fixed, a proper post-mortem and newly added automated test will ensure it doesn't happen the same way again.

Immutability

Sustainable APIs can be consumed at any time, and as long as an API has consumers, it must maintain backward compatibility.

This is simple; it needs only to satisfy two constraints:

A new API version must be able to read existing clients requests

Old clients must be able to read responses from the new API

Breaking one or both of these leaves us with a different API or, at the very least, a new version. The old API should, in either case then, remain as long as needed to avoid breaking clients. Technologies like GraphQL may help, but we still need to be careful. Identical words must still mean the same things; if not, woe to the consumers.

Conclusion

These three points are not sufficient for sustainable API design, but they are necessary. APIs are part of our system's UX, and we must care for them. We need to empathise with our consumers, make our APIs understandable, monitor their performance, and, of course, never break user space.

Patterns for sustainable API-design

To all UX-designers: Stop working alone, start pair designing and embrace collaboration. 

UX-designers may find it frustrating that others have opinions about their design. That it's tiring that anybody can say how the digital product should work.

But it's not your design! As a UX-designer you´re part of a team. What the users experience out there in the real world - that is the design. And so many people were a part of creating it! The whole product team decides what to make, and how it is made. That is what interdisciplinary collaboration really is.

Everybody can design

Everybody can have an opinion about how something should work. Which component from the design system we should use. Or if this or that button should be bigger. It doesn't mean that it will become a great design, but everyone is able to have opinions about it. Think about what these opinions really are. It´s commitment. People who really want the product to become the best product for the users. This is something we as UX-designers should cheer on!

When we UX-designers sit alone and sketch, we end up creating sketches that we hand over to others. While sketching we consider lots of different possibilities and end up making many small and big decisions in the process. We might think that these sketches are the design of the product, but what it really is is just a way of communicating what the team could develop. It´s 2022.  We can't continue with handovers in an agile team making digital solutions! If we simply hand over sketches, we are not collaborating. We are wasting time on misunderstandings between team members. If you get input and the discussion happens after you have landed on what you think is the best, that will not make a useful discussion! If you think we don't have time for the interdisciplinary discussions, that it will take too much time, I’m here to tell you that those discussions will come anyway but they will just come at a later stage. If we continue with handovers we remove the possibility of developing co-ownership for the product we make. An ownership to the whole product, and to all those big and small decisions on why it looks like it does, and works like it does.

Please stop working alone. Start pair designing!

Don't work alone with your sketches. I’m not saying this is easy. There will be more discussions and disagreements than if you sit with your design by yourself. Try to pair design with your team. Include the developers and the product manager. We might have to think a bit more about our arguments and explain why we think that a radio button rather than a dropdown-menu works best in this context. Or why we should make this rather than that. It might be a bit more stressful to dig deep to find the words to argue. But maybe this can lead to a better product over all?

The whole group that is pair designing has to argue and explain their opinions. No one can continue to throw out suggestions or opinions, but rather start to explain why they think one product decision is better than the other. Dear UX-designer, give your team the opportunity to be closer to the big and small product decisions. This gives everyone the opportunity to understand the complexity around the users and the domain that we need to have knowledge about to make the best product choices.

If you think that you can't start working like this in your team. If you will be too unpleasant. If it's too stressful to discuss with your closest collaborators... Then you have to do something about that challenge. Try a Team Canvas, build psychological safety, and so on.

Stop handing over sketches in your team. Involve the team, sketch together, and empower the team to see the users perspective and start pair designing. Don´t bother being right. There is no perfect way to design a user interface. Decide together how the product should work!

🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥

What did you feel while reading? Did it spark something in you? Do you agree or disagree? Join the discussion on UX Norge's slack (Norwegian) or share this article with your colleagues and start a debate! Remember that the goal of Brannfakler is to start discussion!

Dear UX-designers, don't work alone!

Er du som meg — fersk ut av studiet med lite reell arbeidserfaring? Er du selvutnevnt toppkonsulent med mange års bransjeerfaring innen smidig arbeidsmetodikk ? Uavhengig av hvem du er, vil jeg tro at nettopp du kan ha godt av å lese Accelerate.

Dette blogginnlegget er ikke en oppsummering av Accelerate; hensikten er å gi en kort beskrivelse av eget læringsutbytte for å inspirere andre til å lese boka. Accelerate kalles ofte utvikleres bibel og tar for seg digital produktutvikling i lys av DevOps. På tross av det tydelige tekniske fokuset er det en nyttig bok å lese for alle som jobber i selskaper hvor digitale flater er en sentral del av verdiforslaget — alt fra bank og finans til retail. For effektivt å kommunisere læringsutbyttet forsøker jeg å besvare følgende to spørsmål:

Hvordan kan forretningsrådgivere bidra til å drive god digital produktutvikling?

Hva kan man lære av Accelerate som ikke direkte omhandler digital produktutvikling?

Hvordan kan forretningsrådgivere bidra til å drive god digital produktutvikling?

Dette spørsmålet har et todelt svar. For det første virker boka omforenende ved å bidra til forståelse for prinsipper og begreper fra Agile og DevOps, og for det andre tilbyr den konkrete verktøy for hvordan man øker kvaliteten på digital produktutvikling.

Utviklere er godt kjent med prinsipper og begreper fra Agile og DevOps. Disse legger føringer for hvordan man jobber med sprinter i mindre team, hvor hyppige og mindre leveranser legger til rette for høy leveransehastighet og kode av høy kvalitet. Dersom man jobber sammen med utviklingsteam er det derfor viktig med god kjennskap til de samme prinsippene og begrepene for å kunne kommunisere godt sammen. Misforståelser som følge av uklar kommunikasjon reduserer både hastigheten og kvaliteten på arbeidet, og et første steg for å unngå dette kan derfor være å lese Accelerate. Ved å omforenes om de samme begrepene vil man i fellesskap yte bedre.

I tillegg til å virke omforenende tilbyr Accelerate konkrete parametere for å måle kvaliteten på digital produktutvikling, og konkrete nøkkelkapabiliteter for å forbedre selskapers evne til å drive digital produktutvikling. Boka åpner med å påstå at alle selskaper er avhengig av digitale løsninger for å lykkes ettersom forbrukere og konsumenter av tjenester, uavhengig av bransje, forventer sømløse digitale kontaktflater. For å vite om man lykkes med digital produktutvikling må man kunne måle kvaliteten på utviklingen, og Accelerate foreslår fire objektive parametere som tar for seg både utviklingshastighet og -kvalitet. Ved hjelp av disse parameterne kan man isolere selskapene som lykkes og lære av disse uten tidligere bias. Fellestrekk fra disse selskapene har ledet frem til nøkkelkapabiliteter man kan anvende for å lykkes med digital produktutvikling. Accelerate virker dermed som en verktøykasse.

Hva kan man lære av Accelerate som ikke direkte omhandler digital produktutvikling?

Også dette spørsmålet har et todelt svar. For det første bidrar Accelerate gjennom DevOps til å forstå viktigheten av å vektlegge resultater heller enn gjøremål, og helheten heller enn enkelte team. Den andre delen leses ut av bokas fokus på faktabaserte beslutninger og anbefalinger, og hvordan det er viktig for alle beslutningstakere.

«Du har ikke gjort en dritt før du har pusha til prod»; under høstens onboarding ble dette løftet frem som et mantra for alle utviklerne i Bekk. Sagt med andre ord skal man måle kvaliteten på det man produserer, heller enn prosessen som kreves for å komme i mål. I tillegg til dette fokuserer Accelerate, basert direkte på prinsipper fra DevOps, på viktigheten av å omforenes om felles mål. Kjernen i DevOps er å knytte digital produktutvikling (software developement) til forvaltning av kode (operations) for nettopp å sikre både utviklingshastighet og -kvalitet. Dette kan man lære av selv om man ikke jobber direkte med digital produktutvikling — mål det man produserer, og sørg for at man jobber mot felles mål. Dersom man sørger for autonome team med få gjensidige avhengigheter vil man jobbe effektivt med høy grad av eierskap til egne arbeidsoppgaver. Gjennom hyppige tilbakemeldinger vil man sikre felles forankring om hva man ønsker å oppnå, og man vil raskere kunne gjøre endringer om man er på galt spor. Dette er arbeidsmetodikk som er nyttig for alt fra konsulenter og deres kunder, salg- og markedsavdelinger med tett kundekontakt og F&U i dialog med produksjonsavdelinger.

Datadreven argumentasjon og beslutninger kan testes og måles, og dermed verifiseres. Grunnen til at Accelerate er en bok man kan stole på er nettopp at den er skrevet basert på fire år med forskning og et solid beslutningsgrunnlag. Én av tre deler i boka beskriver forskningsmetoden, og dette skaper troverdighet hos leseren. Dette i seg selv er noe man kan lære av. Faktabaserte og datadrevne beslutninger har tyngde uavhengig av hvem som presenterer dem, så lenge dataen i seg selv er pålitelig. Alle yrkesaktive burde derfor tilstrebe å basere argumentasjon og beslutninger på et godt datagrunnlag. Ved å gjøre dette skaper man troverdighet og tar bedre beslutninger, uavhengig av om vitnemålet fremdeles lukter printer eller om luggen er så grå at det ikke er rom for mer erfaring.


Hvorfor bør alle lese Accelerate?

Having a fast and snappy site makes for happy users who are more likely to return to your site. Low quality image placeholders (LQIP) might be what you need to make for a pleasant loading experience for your users.

Challenge

Making a website can be an easy task, but making sure that it loads fast and is available to the majority of your users, whom might be on spotty or bad networks can be challenging. Especially if your site has a lot of high resolution images that needs to be downloaded. This can harm your sites web vitals and especially the First Contentful Paint and the Cumulative Layout Shift thus punishing your sites performance and your users. Fortunately there are different solutions to this problem, one of which I am going to tell you about now.

Introducing Primitive

Primitive is a command line tool and a native Mac application that takes an input image and transforms it to a generated image containing simple geometric primitives. This post focuses on the command line tool. The generated image from Primitive will be a lot smaller in size and therefore it will also load faster. Adding a little blur into the mix as well will give you a great starting point for exceptionally fast load times on your site.

How Primitive works is beyond the scope of this article, but feel free to read more at the Github repository.


Getting started with the CLI version

To get started with Primitive’s command line interface you will have to do the following:

Download and install Go

Then run go install github.com/fogleman/primitive@latest

Now run primitive and you should see the options available through Primitive in your terminal

If the primitive command does not work you might want to add the following to your path: export PATH=$PATH:$(go env GOPATH)/bin

When you have the primitive command running we can start to experiment with the capabilities of Primitive. Let us see how we can generate a jpg image consisting of 100 triangles using this nice image of a parrot shot by Andrew Pons from Unsplash. I downloaded the image and renamed it to image.jpg for brevity.


The command to generate a jpg image of 100 triangles will be

primitive -i image.jpg -o output.jpg -n 100 -m 1

This command will generate the following picture

and as we can see, the new image is only 114 kB and will thus load faster than the high resolution original.

Primitive also supports other output formats if you want to experiment.

If we add some blur to the image, it is hard to tell that the image consists of only triangles and it can therefore be used as a nice blurred variant of the image while your browser fetches the high resolution version.

By applying the blur we have also been able to shave another 50% of the file size, making the loading times on even slow 3G networks quicker.

If we just blur the original image, we shave of a decent amount of bytes, but the size is still 656 kB. Over 10 times the size of the converted primitive image with blur! 

If we render the four images next to each other, and simulate a fast 3G network connection in our developer tools we can clearly see the impact of loading times for the different images.

How to use the images in real life

We now have one or more blurred images that we want to use in our application, but how do use them, and perhaps more importantly, how do we make sure our beautiful high resolution images loads in the background and are automatically replaced when they are downloaded? I will show you an example using Javascript and a library called vanilla-lazyload.

We start by adding the markup for our image

we then include the vanilla-lazyload library at the end of our DOM before instantiating it.

and when we now load our site, the image is first blurred before the original image presents it self in all its glory.

Keep in mind when using javascript libraries that the javascript has to be downloaded to the client device before executing, thus adding a overhead before the original image will render. You might want to compare the trade off before choosing a library such as vanilla-lazyload and then shipping to production.

Bonus tip 1

If you use Next.js as your choice of framework, you will get a very powerful image component included. I won't go into detail on how to use the image component, but feel free to have a look at the placeholder property for creating a blurred effect while the high resolution image is being fetched in the background.

Bonus tip 2

If you use Sanity as your CMS of choice, they have a very powerful asset pipeline for transforming content. I would take a look at the image transformation options and see if you can serve a small blurred variant of your image before fetching the high resolution image.

Conclusion

As I have demonstrated in this post, creating blurred versions of your high resolution images can have a serious positive impact on your web vitals, making your users happier by providing a pleasant experience in regards to load times for your app. Having a fast initial load time for your app will increase your chances of keeping your users longer on your site because they won't leave when the site takes too long to load.

Accelerate your site's load times with geometric primitives

Hvordan skal vi komme til nullutslipp for produksjon av elektrisk kraft? Fornybare energikilder er åpenbart en del av svaret. Hvilke problemstillinger må vi løse for å kunne fase ut fossilkraft?

Elektrisitet er en kritisk ressurs for det moderne samfunnet. Strømproduksjon er i stor grad basert på kull, olje og gass. Veien til nullutslipp innebærer å erstatte fossilkraft med fornybar energi.

Sol- og vindkraft er variabel. Det er ikke sol på natta, vinteren kan være lang og solfattig, og noen ganger er det vindstille. Hvordan kan vi løse dette?


I denne presentasjonen diskuterer Jesse Jenkins en modell som demonstrerer at nullutslipps-kraftnettet trenger tilgang på stabil baselast. Å bygge ut overkapasitet av vind og sol vil medføre at lønnsomheten reduseres. Langtidslagring av variabel energiproduksjon er helt nødvendig for å komme til nullutslipp av kraftproduksjon; mer om dette i en annen luke.

Decarbonizing Electricity: The Critical Role of Firm Low-Carbon Resources | Jesse Jenkins (YouTube)

Veien til nullutslipp for elektrisk kraft

Dagens designtips er en artikkelserie hvor forskjellige designere fra Bekk forteller om jobben de gjør, hvilke utfordringer de møter på, og kanskje kommer med et lite tips!

Hvem er jeg?

Anna Regine

28 år gammel

Kommer fra Ålesund

Studerte design ved Arkitektur og Designhøgskolen i Oslo

Jobbet som designer i 2 år

Hvorfor ble jeg designer? Jeg var glad i å tegne og jobbe visuelt. Å kunne drive med problemløsning med det som utgangspunkt trigget meg til å gå i den retningen. For øyeblikket er jeg i en avsluttende fase for to forskjellige kunder. Spennende prosjekter venter, og jeg gleder meg til å grave i nye problemstillinger!



Hva gjør jeg?

I det siste har jeg blant annet jobbet en del med Elbil-lading, og nøste opp i hvordan dette kan oppleves mest mulig smertefritt når du har parkert bilen din i et parkeringshus.

Det har vært spesielt spennende å jobbe med et fysisk produkt (selve laderen) i sammenheng med et digitalt produkt. Her må man virkelig tenke på konteksten brukeren står i, og sammenhengen mellom de to flatene. I tillegg til å legge opp en logisk flyt både på lader og web, har vi fått rom til å leke litt med den visuelle profilen ved å lage animasjoner og illustrasjoner som bygger opp under de ulike stegene. Det har også vært gøy å gjøre litt feltstudier - kjøre rundt og teste de million forskjellige lade-løsningene som finnes der ute. Jeg har virkelig opparbeidet meg sympati for El-bilisten.


Noe som har vært utfordrende med denne prosessen er kanskje at det er overraskende mange aktører involvert. Laderprodusenter, strømleverandører, de som drifter parkeringshuset, de som eier parkeringshuset.. Så har man selvfølgelig sluttbrukerne, og kanskje bedrifter som leier parkeringsplasser. Ikke bare vil mange av disse aktørene ha logoen sin over alt, men det er også mange meninger, og det kan være utfordrende å manøvrere i når meningene er motstridende. Et klassisk designdilemma, altså!



Hvilket tips ville jeg gitt meg selv i starten av oppdraget?

Dette er kanskje ikke konkret et design-tips, men heller et tips til alle som sitter i et team og skal lage noe sammen, og har mulighet å påvirke prosess og resultat! Og kanskje spesielt et tips til konsulenter, som kommer “utenfra”. Det kan jo av og til skapes noen skiller på hvem er konsulent og ikke, alt ettersom hvordan teamet er satt sammen. Mitt tips vil nok være å prøve bryte ned disse skillene så fort som mulig og bygge relasjoner til de du jobber med. Vi er ett team og vi prøver å løse ting sammen! Når man bruker tid på dette vil det nok bli lettere for andre å forstå idéene dine (og ikke minst for deg å forstå deres idéer) uten å bli den konsulenten som kommer inn med masse idéer og vil endre på ting. Da kan det bli vanskelig å få gjennomslag.

2-Dec

Today's posts

Patterns for sustainable API-design

Dear UX-designers, don't work alone!

Hvorfor bør alle lese Accelerate?

Accelerate your site's load times with geometric primitives

Veien til nullutslipp for elektrisk kraft

Dagens designtips