{"id":20113,"date":"2020-05-08T16:55:11","date_gmt":"2020-05-08T15:55:11","guid":{"rendered":"https:\/\/marvel7077.wpengine.com\/?p=20113"},"modified":"2022-06-01T09:10:48","modified_gmt":"2022-06-01T08:10:48","slug":"api-design-like-designing-user-experience","status":"publish","type":"post","link":"https:\/\/shopjessicabuckley.com\/blog\/api-design-like-designing-user-experience\/","title":{"rendered":"Design APIs like you design User experience"},"content":{"rendered":"

What is User Experience?<\/h2>\n

User Experience (UX) is the value that you provide to your users when they are using your product. It is a term that is mostly associated with beautiful looking User Interfaces. But, by principle:<\/p>\n

User Experience Design<\/em><\/a> (UXD or UED) \u201cis the process of enhancing user satisfaction with a product by improving the usability, accessibility, and pleasure provided in the interaction with the product.\u201d<\/em><\/span><\/p>\n

Designers spend a decent amount of time to make sure that they make every interaction, every UI element as delightful as possible.<\/p>\n

Producing the best type of UX is mainly processes \u2014 the processes that Design\/UX teams use to make sure that their design is valuable, desirable, and usable to the community. It is not just about providing a beautiful UI. They make sure that in the design process all stakeholders are involved so that there are no sudden surprises towards the end. They also do enough research, user testing<\/a> and prototyping<\/a> to make sure that all the ideas or designs they are generating, those resonate with the target users.<\/p>\n

<\/div>
<\/svg><\/div>

\"Design is not just what it looks like and feels like. Design is how it works.\" \u2014 Steve Jobs.<\/p><\/span><\/blockquote>\n

\"\"<\/a><\/p>\n

Why you should care about API Design?<\/h2>\n

The way we see an API\u2019s lifecycle at Postman, it contains stages like Designing, Debugging, Automated testing<\/a>, Documenting the API, Monitoring and Publishing the API so the end users can start consuming it.<\/p>\n

\"\"\"\"<\/a>API Lifecycle<\/p>\n

\u201cDesigning and Mocking an API\u201d is the first and most important step of this lifecycle. Any good engineer can tell that if you start with a shaky foundation or bad bedrock, you\u2019re going to collapse, and the same is true for APIs. If you haven\u2019t done a good job in designing the API, it will have cascading effects on other steps in the lifecycle.<\/p>\n

When APIs have already been built, changes are difficult, expensive and time intensive. Even worse, the changes to published APIs might break any client using the API. The design allows for planning all the details, iterating over several proposals and perform what-if analysis. Moreover, changes made to the API in the designing stage are easy and cheap to perform<\/a>.<\/p>\n

<\/div>
<\/svg><\/div>

\"API Design helps us to avoid building the wrong API, or API in the wrong way.\"<\/p><\/span><\/blockquote>\n

Still, you will find developers spending more time on developing and coding their APIs rather than designing them. APIs are considered to be consumed by machines and not a user-facing entity, as a result of which many organizations don\u2019t spend enough attention and resources to set up a design process for APIs. But today, when the microservice architecture is taking the world by storm, APIs are starting to look more like a product rather than a technology. They should be seen as a way to provide the functionality to end user.<\/p>\n

"In the API space, we build something on a machine for a machine to use and this is wrong because there are people on the other side of API clients."\u2014 Ronnie Mitra<\/a>, Director of Technology at Publicis Sapient<\/span><\/p>\n

Designing a better UX, but for APIs<\/h2>\n

Many RESTful APIs that are designed today are nothing more than object browsers delivering internal representations of the domain\/business objects over HTTP\/S as a transport layer. So, how can you get better in designing APIs, how can you make sure all the APIs that you design follow consistent patterns, how can you make sure that new people joining the team do not reinvent the wheel of making design decisions about API that rest of the organization has learned over time. If you read those above questions again what you will find missing is a process of API design similar to the one UX designers employ and these are the kinds of problems that are being solved by them every day.<\/p>\n

A great UX should ideally follow the usability rules defined by Peter Morville<\/a> known as UX Honeycomb<\/a>.<\/p>\n

\"\"\"\"<\/a>The UX Honeycomb<\/p>\n

In order to design an API with a great UX, you should answer these questions while designing it:<\/p>\n

    \n
  1. Useful<\/strong>: Is the API useful from an end user\u2019s point of view?<\/li>\n
  2. Usable<\/strong>: Can the API be quickly used by a developer and provide easy-to-use functionality?<\/li>\n
  3. Desirable<\/strong>: Is the functionality provided by the API something that generates desire in developers and end users?<\/li>\n
  4. Findable<\/strong>: Can the API documentation be found easily, and can developers use it immediately?<\/li>\n
  5. Accessible<\/strong>: Can the API provide functionality for end users who have technical constraints\/limitations in consuming it?<\/li>\n
  6. Credible<\/strong>: Is the data provided by the API trustworthy?<\/li>\n
  7. Valuable<\/strong>: Does the API contribute to the company\u2019s bottom line and improve customer satisfaction?<\/li>\n<\/ol>\n

    Defining a Design Process for APIs<\/h2>\n

    The strength of a design lies as much in the steps taken to create it as in the final result. A design process helps you to remain transparent and efficient while designing a solution. It sets a clear expectation and decreases the risk of delivering unwanted results.<\/p>\n

    The Double Diamond<\/a> design process by the British Design Council<\/a> is one of such many design processes. It allows people to make intentional design decisions by exploring various options (divergent thinking) while validating stronger ones and weeding out the weaker ones (convergent thinking).<\/p>\n

    \"\"\"\"<\/a>The Double Diamond design process<\/p>\n

    This approach will help you in achieving two of the most important things in any design process:<\/p>\n

      \n
    1. Designing the Right Thing<\/li>\n
    2. Designing the Thing Right<\/li>\n<\/ol>\n

      Designing the Right Thing<\/h2>\n

      This phase is split into Discover\/Research<\/em> and Define\/Synthesis<\/em>. While designing something new it is very easy for people to blow the actual scope of the problem and put all their effort into designing something that no one actually wants or will use. This phase of designing keeps us grounded and makes sure we are designing for the right thing by doing diligent research and defining the right problem statement to solve.<\/p>\n

      Discover\/Research<\/h3>\n

      When you are building a new Product, Feature or an API you are trying to solve a problem. In order to provide a solution, you need to first understand the problem. Always start by acquiring the Domain Knowledge<\/em> about the problem. Try to understand what problem you are trying to solve, who is this being built for etc. Clarify on the use-cases and the requirements. Research on existing solutions to understand how they are solving the same problem and what you can learn from their architectural\/technical decisions. Talk to all the teams inside\/outside your organization that are stakeholders for this new API which might include Product Team, Design Team, Security Team, etc. Their different perspective will give you a broader view to think about your API and the technical decisions that you are planning to take from that point onwards.<\/p>\n

      You can also leverage the Postman API Network<\/a> for your research or reference to find out how different organization\u2019s APIs looks like. Postman\u2019s API Network contains a diverse list of APIs which are published by organizations from a lot of different domains and industries. For example, if you are building the API in FinTech space, for your research you can check some of the APIs published by other organizations in the Financial Services section.<\/p>\n

      \"\"\"\"<\/a>API Network inside Postman app<\/p>\n

      This step will result in a lot of unstructured information, overlapping and conflicting use-cases\/requirements. So in the next step, structure this information so that you can make better design decisions around your API.<\/p>\n

      Define\/Synthesis<\/h3>\n

      From the raw data, find trends and insights that span across different users and scenarios. Try to pin down exact use-cases and requirements you are planning to cater. This stage of the process is also the right time to flag off any dependency that your API might have on another service, which is quite common in a microservices architecture. Define your Resource Models and relationships between them, which will help you in identifying all the Resources for which you would need to expose APIs. You should also clearly outline the behavior and expectations of the API so that consumers don\u2019t have to make any assumptions while using your APIs. Doing this will help you identify the amount of business logic that will be part of the service or the client.<\/p>\n

      Designing the Thing Right<\/h2>\n

      This phase is split into Develop\/Ideation<\/em> and\u00a0Deliver\/Implementation<\/em>. This phase will ensure that whatever you decide to design, it\u2019s designed the right way to ensure that you are not compromising with quality, consistency, security and the best practices outlined by the organization\/industry.<\/p>\n

      Develop\/Ideation:<\/h3>\n

      Once you are clear on \u2018what needs to achieved\u2019 using APIs, it\u2019s time to design those APIs so that you can communicate on what you as API provider intent to ship. API Description Languages such as OpenAPI\/Swagger, RAML, etc are a great way to express important aspects of an API. Especially the frontend design decisions and architectural design decisions, which are visible to the consumer, can be captured by API description languages. But one drawback with these API description languages is that they can get way too technical, verbose and difficult to collaborate upon. So alternatively what you can do is import Swagger<\/a>, OpenAPI<\/a> or RAML<\/a> specification files into Postman Collection<\/a>.<\/p>\n

      If you have worked closely with a UX\/Design team before you would have noticed that some of the outcomes at the end of their designing process are documentation around all the features and interactions, representation of various states of UI (error states, empty states, etc) and a prototype which demonstrates the exact interaction with the UI and what should be the expected outcome.<\/p>\n

      Using Postman collections you can also achieve the same outcome for your APIs and provide total transparency to all the surrounding stakeholders.<\/p>\n