DEV Community: Melinda Gutermuth

GraphQL interview questions

Melinda Gutermuth — Mon, 26 Feb 2024 17:18:53 +0000

According to Postman’s 2023 State of the API Report, GraphQL has taken the place of SOAP as the third most popular API architectural style, following only REST and Webhooks. Whether you’re applying to be a developer, technical lead, data engineer, or technical product manager, these answers to some of the most common GraphQL interview questions will help you navigate the interview process with confidence.

GraphQL interview questions and answers: beginner

In this section, we’ll go over some of the most common beginner-level questions and answers about GraphQL. You might be asked these questions if you’re applying for a role as a frontend developer, web or mobile app developer, product manager, or UI/UX designer at an API-first company.

What is GraphQL?

GraphQL is both a query language and a server-side runtime for APIs that allows clients to request the exact data they need. Unlike traditional REST APIs that might return more information than you’re looking for, GraphQL offers a way to interact with data services that prevents data over- or under-fetching. Web and mobile applications often use GraphQL to enhance data retrieval and manipulation, leveraging its server-side runtime to resolve queries.

What is the difference between a mutation and a query in GraphQL?

In GraphQL, mutations are used to write or change data, while queries are used to read data. Queries are used for operations that do not have side effects, such as data retrieval, while mutations are used for operations that can modify data, such as those that create, update, or delete records.

What is a GraphQL schema?

A GraphQL schema describes the capabilities of a GraphQL server by defining a list of types and directives. It describes the types of data that can be queried and manipulated, the relationships between these types, and the queries and mutations that are available. The schema acts as a contract that specifies what information the client may request and how the server will respond.

What are scalar types in GraphQL?

Scalar types are basic atomic data types in GraphQL that represent single values. They include types like String for text, Int for integers, Float for floating-point numbers, Boolean for true or false values, and ID for unique identifiers. Scalars are used to represent the leaves of the GraphQL query tree, serving as the foundation for more complex data structures.

What is an exclamation point in GraphQL?

In GraphQL, an exclamation point (!) indicates that a field in a query or a field argument is non-nullable. This means that the field must contain a value and cannot be empty. When used with a field, it ensures that the server always returns a value that is not null. When used with a field argument, it indicates that the client must provide the argument and it cannot be left out.

What are resolvers in GraphQL?

In GraphQL, each schema field corresponds to a function known as the resolver. The resolver returns the value for a given field in an operation. Resolvers provide instructions on how to compute or retrieve data from the server or other sources. They are a crucial part of implementing GraphQL servers because they translate the fields in the schema to the real data sources—which might be databases, REST APIs, or other services.

When is GraphQL useful?

GraphQL is useful in situations where applications require efficient and precise data retrieval, real-time updates, and complex data relationships. It also functions well in situations where there are multiple clients, different data requirements, and the need to compile information from various sources. Additionally, GraphQL can be used as a layer to overcome the limitations of RESTful or SOAP APIs by providing a more flexible querying interface.

What are the key concepts of the GraphQL query language?

The key concepts of the GraphQL query language revolve around its schema-driven approach. GraphQL defines types and relationships in a schema, allowing clients to request precisely the data they need using queries. Mutations enable clients to modify data, while fields specify what data to retrieve. Arguments, aliases, and fragments enhance query flexibility, and variables make queries dynamic. Directives offer conditional execution, and introspection allows clients to explore a schema’s structure and capabilities, making GraphQL a powerful and versatile querying language.

GraphQL interview questions and answers: intermediate

This section includes some common GraphQL interview questions and answers at the intermediate level. You might be asked these questions if you’re applying for a role as a backend developer, DevOps engineer, technical product manager, or solutions architect.

What are variables in GraphQL, and how do you use them?

Variables in GraphQL are dynamic values that can be passed as arguments in queries or mutations, allowing for more flexible and reusable code. You define variables in your query or mutation and then pass the actual values when executing the request. With this method, you can write generic mutations or queries where the details are provided at runtime.

What is introspection in GraphQL, and how is it useful?

GraphQL introspection enables clients to ask the GraphQL server questions about the schema, including available types, fields, and directives. It’s useful for building client-side tools that need to understand the schema, and it supports auto-generating queries, documentation, and validating queries against the schema before sending them. As a result, GraphQL APIs are self-documenting and easier to explore and integrate.

How do you do authentication and authorization in GraphQL?

Authentication is usually handled outside of the GraphQL layer, typically through HTTP headers such as JSON Web Tokens (JWT). Authorization is implemented in GraphQL resolvers by checking permissions before returning data or performing mutations. Authentication verifies a user’s identity, while authorization determines their access rights to various parts of the GraphQL schema.

How do you do error handling in GraphQL?

Instead of using traditional HTTP status codes, errors are returned in the response alongside the data. These errors can be generated by the GraphQL server (for syntax or validation errors), as well as by resolvers (for business logic or runtime errors). Clients can then parse these errors and handle them accordingly, often using the error message and optional fields—like error codes or paths—to identify the nature and location of the error.

How do you handle and report errors in a production GraphQL API?

Errors in a production GraphQL API are handled by sending user-friendly error messages to the client and logging them to a monitoring system for analysis and alerting. Sensitive data is omitted for security reasons, but critical details about the error context—such as the query, variables, and user information—are recorded for debugging purposes. Additionally, operational errors are differentiated from developer errors in order to help with response and mitigation strategies.

What is the main difference between GraphQL and REST?

The main difference between GraphQL and REST is their approach to data retrieval. GraphQL allows clients to request exactly the data they need in a single query, reducing over-fetching and under-fetching, while REST typically uses predefined endpoints that return fixed data structures. GraphQL enables clients to aggregate data from multiple sources in a single request, but REST often requires multiple round-trips to different endpoints to gather all necessary data.

What are the advantages and disadvantages of GraphQL?

GraphQL has the advantages of efficient data fetching, customized client requests, and a strongly typed schema that makes API exploration and validation easier. But compared to conventional REST APIs, its disadvantages include a steeper learning curve, potentially intensive server-side processing, and complex query optimization. Additionally, GraphQL queries are dynamic, which can make caching more of a challenge.

How can you implement versioning in a GraphQL API without breaking existing clients?

GraphQL developers can successfully implement API versioning by using the schema extension, which allows them to add or change fields and types without affecting or deleting existing ones. This approach, known as “evolutionary” or “continuous” versioning, allows clients to continue using the original schema while new clients use the extended schema. Developers can also preserve backward compatibility by deprecating obsolete fields rather than deleting them and by using field aliases for major changes.

GraphQL interview questions and answers: advanced

We’ll now go over some advanced GraphQL questions. If you’re applying for a role as a GraphQL developer, senior full-stack developer, API architect, or performance engineer, you might be asked some of the more in-depth questions in this section.

What is batching in GraphQL, and what is its impact on performance?

Batching in GraphQL refers to the process of combining multiple queries or mutations into a single HTTP request, which reduces the number of network round trips. This approach can significantly improve performance by minimizing the latency and overhead associated with making multiple separate requests—particularly in scenarios with multiple concurrent data requirements. However, it requires careful management on the server side to efficiently resolve these batched requests without overloading the system; tools like DataLoader can help.

How can you optimize GraphQL queries for performance, especially when dealing with deeply nested data?

To optimize GraphQL queries for performance, use query depth limiting and complexity analysis to avoid costly database operations. You should also use efficient data loading techniques, such as batching and caching at the data fetching layer, to reduce database load. Additionally, consider implementing a persisted queries mechanism, which will store and efficiently retrieve frequently used or expensive queries. This approach will reduce the need for query parsing and validation on each request.

What are some security considerations and best practices when exposing a GraphQL API to the public internet?

Strong authentication and authorization procedures, input validation and sanitization, and limitations on query complexity and depth are essential when opening a GraphQL API to public access. It’s also important to use API monitoring and rate-limiting techniques to identify and stop abusive traffic patterns. Additionally, keep the GraphQL schema secure and don’t reveal sensitive data in error messages in order to protect against information leakage and potential exploitation.

How would you protect against common security vulnerabilities, like SQL injection or DDoS attacks, in a GraphQL API?

To protect a GraphQL API against SQL injection, use parameterized queries or prepared statements in database operations, and rigorously validate and sanitize all user inputs. To defend against DDoS attacks, implement rate limiting, query complexity analysis, and depth limiting to control the load on your server. As an added measure, use monitoring systems and Web Application Firewalls (WAFs) to identify and address suspicious traffic or activities.

What are the benefits and challenges of federated GraphQL schemas in a microservices architecture?

Federated GraphQL schemas in a microservice-based architecture allow different services to define their own part of the schema, enabling a scalable and modular approach that aligns well with microservice principles. By giving clients access to a single API gateway, this federation increases API usability and development efficiency. However, challenges include maintaining schema consistency across services, handling cross-cutting concerns like authorization and error handling, and ensuring efficient query execution without incurring significant inter-service communication overhead.

How can you create custom directives in GraphQL, and what are some use cases for them?

Custom directives in GraphQL can be defined in the schema language and implemented on the server side, typically in the GraphQL server configuration. These directives can be used to change how queries or mutations are executed; for example, they can be used to perform field-level transformations, enforce permissions, or implement custom business logic. Some use cases include logging, authentication, field deprecation, and dynamically changing query responses based on certain conditions or user roles.

What is the role of serverless functions in a serverless GraphQL architecture, and when might you use them?

A serverless GraphQL architecture eliminates the requirement for a dedicated, continuously operating server by using serverless functions to carry out the business logic of GraphQL resolvers. Incoming GraphQL requests are handled by these dynamically allocated functions, which enable cost-effective scaling based on request load. They are particularly useful for handling sporadic or unpredictable traffic, executing computationally intensive tasks, and integrating with other serverless services or APIs. These benefits make serverless functions a flexible and scalable backend solution.

How can you implement real-time updates in GraphQL using subscriptions?

The subscriptions feature in GraphQL enables clients to receive real-time data from the server over a persistent connection, usually through WebSockets, which is useful for implementing real-time updates. When a client subscribes to a specific event, the GraphQL server pushes updates to the client as the relevant data changes, keeping the client in sync. This is especially useful for features such as live chats, real-time notifications, or any scenario in which data must be updated in real time on the client side.

Conclusion

This article has covered a wide range of GraphQL topics, from the basics to more advanced strategies and concepts. GraphQL offers an incredibly flexible way to work with APIs, as demonstrated by the variety of questions we have answered. Whether you’re a developer, a product manager, or a user experience designer, GraphQL knowledge is critical to your success in the software industry today.

Technical review by Meenakshi Dhanani.

The post GraphQL interview questions appeared first on Postman Blog.

API design interview questions

Melinda Gutermuth — Mon, 27 Nov 2023 16:53:38 +0000

According to Postman’s 2023 State of the API report, over 75% of respondents agree that developers at API-first companies are more productive, create better software, and integrate faster with partners. With this in mind, it’s no surprise that so many people want to be a part of an API-first organization. Whether you’re applying to be a developer, QA engineer, data scientist, or technical product manager, these answers to some of the most common API design interview questions will help you navigate the interview process with confidence.

API design interview questions and answers: beginner

In this section, we’ll go over some of the most common beginner-level questions and answers about API design. These are questions you might be asked if you’re applying for a role as a product manager, technical writer, UX/UI designer, or sales and marketing professional at an API-first organization.

What is API design?

API design is the process of making intentional decisions about how an API will allow different software components to interact and exchange data with one another. These decisions, which are captured in a specification format such as OpenAPI or AsyncAPI, help ensure that the API is user-friendly and able to meet both present and future needs.

What is API-first design?

API-first design involves designing an API and its functionality at the beginning of the application development process. When following an API-first design approach, stakeholders create APIs that will serve as the application’s foundation and the contract between various software components, allowing for seamless integration and collaboration.

Why are APIs important in software development?

APIs enable different software components, services, or applications to interact and share data. APIs that are well-designed promote interoperability, efficiency, and reuse while also putting the user experience first. This increases adoption and allows developers to build on existing solutions to quickly and easily create modern and complex applications.

What is a REST API?

REST, which stands for Representational State Transfer, is a set of principles for creating simple, scalable, and flexible systems that can interact and share data over a network. REST APIs are stateless, resource-based, and leverage a standardized set of HTTP methods for client and server communication. REST is the most popular API architectural style and the foundation of the web.

What are the different components of an HTTP request?

The most basic REST APIs use standard HTTP methods like POST, GET, PUT, and DELETE to perform Create, Read, Update, and Delete (CRUD) operations on resources that are represented by URLs. An HTTP request includes four major pieces of information:

Method : A standard verb that describes the action being applied to the resource, such as POST, GET, PUT, or DELETE.
Uniform Resource Identifier (URI): Identifies the resource on the server. A URI, which is also known as an API endpoint, can be either a relative or absolute path, and it may contain data like path or query parameters. For example, /products might identify a list of products, /products?type=book might identify books within the product list, and /products/1234 might identify a specific book.
Request headers : Contain metadata about the request as key-value pairs. For instance, these HTTP headers might include the type of client or browser, the client-supported format, the message body format, and cache settings.
Request body : The payload, which is usually JSON or XML data, that is sent to the server. For example, if you send a POST request to /products, the request body will contain the data for the product you want to create.

What are the different components of an HTTP response?

An HTTP response includes three major components:

HTTP status code : Indicates the outcome of the request, such as 200 OK for success.
Response headers : Contain metadata about the response, including information like the content type, server details, and caching directives.
Response body : The payload that the server sends in response to the request. For example, this could be HTML from a web page, or it might be JSON or XML data from an API.

What is an HTTP status code?

An HTTP status code is a three-digit numeric code that a server returns as part of an HTTP response. The code provides information about the result of the request. For example, a successful request usually returns a 200 OK status code, while an unsuccessful request might return a 404 Not Found status code. HTTP status codes are organized into classes: codes in the 200s are successful, 300s indicate redirection, 400s signify a consumer or client error, and 500s point to a provider or server error.

What are the most common HTTP status codes you see when working with REST APIs?

These are some of the most common HTTP status codes:

200 OK
201 Created
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
503 Service Unavailable

What is a payload?

In the context of APIs, the payload is what goes in the body of the request or response. It contains the data that is sent as part of an API request or response using a POST or GET method. The payload contains the actual information being sent, such as JSON or XML data.

Why is versioning important in API design?

Versioning is crucial to API design because it helps maintain compatibility, offer stability, and reduce disruptions. Versioning also enables incremental updates, supports a wide range of clients, and fosters user and developer confidence. By isolating changes, versioning ensures that existing clients won’t break when improvements or fixes are introduced, which allows for smooth and controlled evolution of the API while encouraging adoption and clear communication about updates and deprecation plans.

API design interview questions and answers: intermediate

This section includes some common API design questions and answers at the intermediate level. These are some of the questions you might be asked in an interview if you’re applying for a role as a full-stack developer, QA engineer, data scientist, or technical product manager.

What are the key principles of good API design?

Good API design prioritizes the needs of API consumers while also being clear and consistent in its naming and behavior, offering helpful error feedback, and using standard and interoperable data formats. A well-designed API should have logical naming conventions, predictable behavior, and be easy to understand and use. It should also evolve gradually and thoughtfully, maintaining backward compatibility to support existing clients while allowing for incremental improvements to meet changing requirements.

How do you ensure consistent API design?

From the beginning, it’s important to establish clear design guidelines and best practices. For instance, naming conventions, endpoint structures, HTTP methods, and response formats should all be standardized. Additionally, conducting regular design reviews, using linting to validate that design conventions are followed, providing clear API documentation, and fostering communication among the development team contribute to maintaining consistency throughout the API’s lifecycle.

How do you handle errors and exceptions in API responses?

When handling errors and exceptions in API responses, it is important to use standard error messages that have meaningful status codes and human-readable descriptions of the problem to help users fix the issue. For client errors (4xx), provide comprehensive error feedback all at once. For server errors (5xx), avoid revealing sensitive system details, like OS versions, databases, or stacktraces, while still offering clear information to help users or API developers troubleshoot.

What is the purpose of pagination in API responses, and how would you design it?

Using pagination in API responses helps clients retrieve and display large amounts of data in smaller, more manageable chunks. Use cursor-based pagination for optimal performance, where an API consumer navigates the data by making a request, then uses the opaque cursor from the response to make their next request with a “next” parameter. They can also leverage a “previous” cursor to retrieve prior data.

If it’s necessary for users to directly access a specific page within your dataset, you can implement index-based pagination. This method separates the data into discrete pages, which clients can request by passing in the number of the “page” as a parameter. Although it can negatively affect performance, index-based pagination can be useful when users require exact control over page navigation within the dataset.

What’s the difference between REST and RESTful?

The word “RESTful” describes APIs or services that adhere to REST principles. To be RESTful, a service or API must follow the rules and best practices defined by REST, such as properly using HTTP methods and representing resources as URLs. Being RESTful also entails hiding server implementation details from clients, which promotes flexibility and scalability. In a RESTful design, efficient caching techniques can also minimize unnecessary data transfers and boost performance.

What are the advantages of RESTful APIs?

RESTful APIs are known for their simplicity and scalability. They map operations to resources using standard HTTP methods, promoting clarity and ease of use. RESTful APIs also encourage loose coupling between clients and servers, making it easier to evolve systems over time, and they benefit from a well-established ecosystem of tools and libraries. In addition, a REST API with a consistent interface and smart design is inherently easy to find and use, even without extensive documentation.

What are the disadvantages of RESTful APIs?

RESTful APIs can encounter issues with data over-fetching or under-fetching. These problems can often be reduced by fine-tuning the API structure for more precise data control, but they can also be an indication of an unsuitable design. Sometimes this issue can be solved by using a different REST API format, such as JSON:API, which allows the retrieval of specific subsets of available fields. If exact control over data fetching is crucial, GraphQL might be a better fit.

Another disadvantage of REST is that its request-response model isn’t built for applications that require live data. Because the client makes a request and then waits for the server to respond, applications can’t fetch real-time data in an efficient way. RESTful APIs must also encode and decode binary files like photos and videos before they can be sent. As a result of this overhead, timeouts may occur when transfers become slower and demand more bandwidth.

How do you handle a long-running operation with a REST API?

Long-running operations are typically handled asynchronously with REST APIs. First, the client initiates the operation and receives an identifier to track its progress. The client can then check the status of the operation until it is finished, as the API server processes it in the background and sends status updates or the final result via the identifier. This approach ensures that long operations do not block the client and provides a scalable and responsive API.

How do you represent a “do something” operation in a REST API?

“Do something” operations are those that need to be performed on a system or application but don’t correspond to a typical CRUD operation. To perform a “do something” operation via a REST API, you can define a resource with a noun that matches the action or the results of the action. You can then use this resource like any other resource—for example, to perform an operation that results in a state change or the creation of a resource, simply execute an action with the POST method and include the action’s input data in the request body. The response should include the action’s output data and the appropriate HTTP status code.

What tools do you consider essential for the API design process?

First and foremost, it’s essential to have a robust API design, documentation, mocking, and testing tool such as Postman. Version control systems, such as Git, are also critical in managing OpenAPI definitions, as they allow for efficient versioning and synchronization to track changes over time. Additionally, linting tools help maintain code quality and consistency throughout your API development process. Together, these tools collectively empower API developers to create well-structured, comprehensively documented, and thoroughly tested APIs, which enhances their usability and ease of integration.

API design interview questions and answers: advanced

In this section, we’ll go over some advanced API design questions. If you’re applying for a role as a backend developer, API designer or architect, DevOps engineer, or solutions architect, you might be asked some of the more in-depth questions in this section.

What is the process of designing an API from scratch?

Define the API’s goals, scope, and purpose first, taking into account the requirements of both developers and end users. This process usually occurs during the initial “Define” phase of the API lifecycle. You should also consider the subject matter, the providing system, and the limitations and preferences of API consumers. These constraints might include factors like supported HTTP methods, industry-specific data formats, or system availability windows.

Next, create a programming interface that is clear, consistent, versatile, evolvable, and user-friendly. To do this, decide which features and capabilities you want your API to have—and then derive actions and resources from those features. Next, define resource paths, choose the appropriate methods, and establish meaningful status codes. As you go, pay attention to the fine-grained modeling of input and output data. Finally, continuously gather feedback to refine and improve the API’s design and functionality over time.

What are some best practices for RESTful API design?

There are many best practices for designing effective RESTful APIs. Start by designing resource paths with meaningful names and clear structures that reflect the relationships between resources. Next, standardize the API’s actions and capabilities by representing them as CRUD operations applied to resources. It’s also important to return meaningful status codes to indicate operation success or failure, maintain overall consistency and predictability, and adhere to established standards in URLs, operation behavior, data organization, naming conventions, and data typing.

To increase performance, make the API cacheable and stateless. Additionally, make sure the right versioning mechanisms are in place to handle changes without causing disruptions. These guidelines bring clarity, consistency, and scalability to API design, which in turn promotes user satisfaction and developer adoption.

How would you handle the versioning and deprecation of an API?

There are several steps you can take to gracefully manage API versioning and deprecation. For instance, use version identifiers in URLs or headers to let clients choose between versions, and introduce new, non-backward-compatible versions only when absolutely necessary. Give each version a long lifespan to identify weaknesses in its design, making only backward-compatible changes, even if it delays some updates and fixes. You can then leverage new versions to introduce major features alongside necessary improvements. If users are eager to use the new features, they’re more likely to accept breaking changes. It’s also important to make sure that clients are aware of changes, which involves providing thorough documentation and precise deprecation timelines. Deprecated APIs can be safely retired after the migration period ends.

How do you handle backward compatibility in API evolution?

Preserving the features and data structures that current clients depend on is essential for maintaining backward compatibility when developing an API. Although it is usually possible to add new features or output data while maintaining compatibility with previous versions, breaking changes may result from things like altering data types or formats, adding or removing values in enumerations, or making an existing query parameter or request body property required.

Avoid breaking client code by not removing or changing any currently supported endpoints or fields without first clearly marking them as deprecated and providing an explanation of how to migrate away from them. Selecting extensible data types and formats early on—such as objects rather than strings or arrays—can also be helpful. With a versioned approach, clients can choose which API version they want to use, so older clients continue to work while newer clients can be safely upgraded at their own pace.

Is it always a problem to introduce a breaking change?

A breaking change may not be a problem if its benefits significantly outweigh the potential disruption to current clients. For instance, releasing a new version with improved performance, security, or features may be essential for the API’s long-term viability. The transition to a new version may be relatively smooth if the API consumer base is small or easily adaptable. Additionally, if the API provider has a well-established deprecation strategy and clear communication channels with consumers, the impact of breaking changes can be managed effectively.

What are caching best practices?

Caching can improve API performance by minimizing redundant data requests and leveraging conditional requests. Using cache keys that specifically identify resources, using the right cache-control headers, and choosing cache expiration strategies that take data volatility into account are some of the most important caching best practices. Effective caching can reduce server load, minimize latency, and improve the overall responsiveness of APIs.

What is content negotiation in HTTP, and how does it relate to API design?

When sending and receiving data over HTTP, the client and server must first agree on a common format and language through a process known as “content negotiation.” Content negotiation enables clients to specify their preferred content type (for example, JSON, XML, CSV, or PDF) and language (for example, English or French), and the server responds accordingly. Content negotiation is crucial because it helps account for the various client preferences and requirements while improving the API’s usability and versatility.

How do you ensure security in API design, especially when handling sensitive data?

To ensure security at the API design level, take a proactive approach. Begin by carefully evaluating the necessity of certain features and data. If a feature or piece of data isn’t absolutely necessary, leaving it out can help prevent security issues. Additionally, use different APIs or operations for sensitive and non-sensitive data and operations. Avoid including sensitive information in URLs, and substitute raw sensitive data with processed, less sensitive alternatives.

You should also consider API authentication and authorization during the API design process. For instance, create and apply OAuth scopes to restrict access, ensuring users only access operations they are authorized for. Additionally, always include access controls in descriptions to help guide implementation, such as indicating which data is accessible to identified consumers. This approach improves API security by reducing unnecessary exposure and effectively enforcing access controls.

How do you ensure you’re creating the “right” API?

Creating the “right” API requires a comprehensive understanding of the problem the API is meant to solve. Begin with a clear definition of the API’s goals, scope, and purpose, taking into account both developer and end-user perspectives. Involve stakeholders on a regular basis, collect feedback, and adapt the API design to changing requirements. Usability testing and user research can help ensure that the design works as intended.

In addition to meeting the initial requirements, the API should be versatile enough to be reused in other contexts. Creating an API that meets the criteria is “doing it right,” but the “right” API is one that does so and is flexible enough to be reused. Make sure the API design continues to be the “right” solution over time by revisiting it on a regular basis and making adjustments based on actual usage and evolving demands.

Conclusion

API design plays an essential role in today’s API-first world. In this article, we’ve gone through numerous API design topics, from the fundamental building blocks to advanced strategies and concepts. The range of questions we’ve answered show how API design is both an art and a science. Whether you’re a developer, a product manager, or a user experience designer, API design knowledge is critical to your success in the software industry today.

Technical review by Arnaud Lauret.

The post API design interview questions appeared first on Postman Blog.

5 ways to set up your Postman team profile for greater success

Melinda Gutermuth — Wed, 30 Aug 2023 07:31:53 +0000

If you’ve been keeping up with the Postman blog, you already know that completing your Postman public profile is an important step toward maximizing adoption of your API. A solid, professional profile for your team can put users at ease, giving them confidence that they’ve found the right place and that your APIs are high quality.

It’s one thing to promote your public APIs when you have a single product. But what if you’re a large enterprise with public APIs that span multiple business units and product lines? How do you set up your teams’ profiles so that your customers can find the API that is relevant to them? Let’s take a look at some examples from the Postman Public API Network.

Give your APIs a strong introduction

Esri is known for its geographic information system (GIS) software, solutions, and services. Their products include desktop GIS software such as ArcGIS Pro and ArcMap, as well as web-based GIS solutions such as ArcGIS Online and ArcGIS Enterprise. Their ArcGIS APIs give developers a set of libraries and interfaces that let them work with GIS data and functions and use them in their apps.

Let’s look at the Esri team profile.

Esri describes their APIs and pins popular workspaces and collections

Here’s how Esri’s team profile is set up:

Uses rich Markdown to introduce and highlight their ArcGIS APIs
Highlights two of their workspaces as well as two of their most popular collections
Includes links to their Twitter, GitHub, and developer documentation

Esri has made it easy for users to find their public APIs by pinning these elements to their team profile, and on top of that, they’re also giving them direction so they know where to start.

Highlight your brands

Meta contains a handful of major social media and networking brands, including WhatsApp, Facebook, Instagram, and many others. WhatsApp is a messaging app that allows users to talk, text, and create group chats with end-to-end encryption and no international call fees, while WhatsApp for Business is designed for businesses to communicate securely with their customers. Facebook allows users to share updates, photos, videos, and other content with their friends. Instagram allows users to upload and share photos and videos, apply filters and editing tools, and add captions and hashtags. On Meta’s Postman profile, each of these brands has a public API.

Let’s check out the Meta team profile.

Meta created a workspace for each of their brands

Here’s how Meta’s team profile is set up:

Has workspaces that correspond to different brands, including WhatsApp, Facebook, and Instagram
Organizes each workspace to suit each brand: WhatsApp has separate collections for different use cases, such as WhatsApp for Business, while Facebook and Instagram only need one collection each
Includes links to their Twitter, GitHub, and developer documentation

Create multiple workspaces for one versatile API

LinkedIn is a site for professionals to connect with each other, build their personal brands, and look for job opportunities. It offers a job search platform, a learning platform, and a content creation platform, among other things. With LinkedIn’s Developer API, you can make apps for custom recruitment and staffing, advertising, and learning management systems.

Let’s check out the LinkedIn team profile.

LinkedIn uses separate workspaces for each function

Here’s how LinkedIn’s team profile is set up:

Provides a strong introduction in the About section
Has workspaces that correspond to different business areas, like marketing, compliance, and talent solutions, and pins them to their profile
Includes links to their Twitter, GitHub, and developer documentation

Whether you’re looking to use the LinkedIn Developer API to create a job posting, pull data and insights about your organization’s LinkedIn content, or integrate LinkedIn Learning courses into your own platform, their team profile will help guide the way.

Manage a profile for each product platform

Oracle is best known for Oracle Database, but they also have a wide range of enterprise software products, including app development tools, business intelligence tools, enterprise software apps, and cloud services. Their APIs allow developers to develop custom apps that integrate with their databases and also access and manipulate the data that is stored there.

Oracle has different team profiles on the Postman API Network for different parts of their business. Let’s start by taking a look at the Oracle Developers team profile.

Oracle creates different teams for different business units

Here’s how the Oracle Developers profile is set up:

Highlights their most popular workspace, Oracle Cloud Infrastructure REST APIs
Pins some popular collections to make it easy to work with their API Gateway API and Anomaly Detection API
Includes links to their Twitter, GitHub, and developer documentation

Though they have many more public APIs and other public workspaces, their profile gives a good overview of the most-used elements.

Oracle also has a team profile for their Oracle Hospitality Integration Platform.

Oracle has a separate team profile for their hospitality software platform

The Oracle Hospitality Integration Platform (OHIP) is a cloud-based integration platform made for the hospitality industry. Their APIs make it easy to connect hospitality systems like property management systems, point-of-sale systems, inventory management systems, and guest loyalty programs in a way that is secure and scalable.

Here’s how the OHIP team’s profile is set up:

Uses a single workspace, Oracle Hospitality APIs
Highlights their three most popular collections
Includes links to their Twitter, GitHub, and developer documentation

By creating a team profile that’s separate from their main Oracle Developers team, Oracle has made it easier for their hospitality integration platform clients to find the APIs they need. You might also notice that both the OHIP and Oracle Developers team profiles link to the same Oracle profile on GitHub, but each team has its own developer landing page and Twitter account.

Oracle also has its MuShop team profile, one of their open source projects.

Oracle has a separate team profile for their microservices demo project

MuShop is an example app that shows how you can use Oracle Cloud Infrastructure to create your own cloud-native, microservices-based e-commerce app. Their set of RESTful APIs can be used to access the Oracle MuShop app’s different services and features, such as browsing products, searching for artists and albums, adding products to a cart, checking out, and managing user profiles.

Here’s how Oracle’s MuShop team profile is set up:

Shows off their Catalogue Service API, their MuShop Catalogue Service collection, and their only workspace, MuShop Microservices
Includes links to their GitHub and developer documentation

Oracle maintains separate team profiles for different business units within the company. With such a large number and wide variety of APIs, this strategy can help consumers focus their search when they’re looking for the right API for their use case.

Use multiple profiles for multiple markets

Cisco is a technology company that makes routers, switches, and other networking equipment, and they offer APIs for all of their networking and communication technology. These APIs let network administrators and developers automate and manage their networks programmatically, as well as connect Cisco’s technology to other systems and services.

Let’s take a look at the Cisco DevNet team profile.

Cisco uses separate team profiles for products that reach separate markets

Here’s how Cisco has set up their DevNet profile:

Highlights Cisco DevNet’s Public Workspace, which is a place where people can learn about Cisco’s APIs and find guides
Pins two of their collections: Cisco SD-WAN-AlwaysOn, which is a part of a software-defined wide area network (SD-WAN) solution that provides secure and scalable office networking, and the Cisco ISE 3.0 ERS REST API, which gives programmatic access to the Cisco ISE network security solution
Includes links to their Twitter, GitHub, and developer documentation

For its cloud-based solution, Cisco has the Cisco Meraki team profile.

Cisco uses a separate team profile for their cloud-based services

Unlike the primary Cisco product line, Cisco Meraki’s networking solutions can be managed in a cloud-based dashboard. This business unit targets a different type of customer, one who’s looking for a solution that’s easy to manage using a dashboard interface.

Here’s how Cisco has set up the Meraki profile:

Highlights Cisco Meraki’s Public Workspace along with collections for their dashboard API

Wrapping it up

These five companies’ products and services cover everything from social networking to networking hardware. Some have many public APIs available, while others might have a single API with a wide range of uses. Like many large companies, they contain different business units that cater to different markets. In each case, these businesses have a wide range of users to serve, and they’ve found a variety of effective ways to reach them.

Which one do you think will work best for your public APIs? Update your team’s public Postman profile today! Be sure to start strong with a profile image that reflects your brand and complement it with a banner image. If you don’t have permission to edit your profile yourself, be sure to share this post with your team’s Community Manager.

The post 5 ways to set up your Postman team profile for greater success appeared first on Postman Blog.

Understanding Asynchronous APIs

Melinda Gutermuth — Wed, 28 Sep 2022 20:01:12 +0000

If you’ve worked mostly with REST APIs, you might not be as familiar with asynchronous API protocols like WebSocket and gRPC. Asynchronous APIs allow you to stream data, send multiple requests at the same time, and manage communication intelligently between services, while synchronous APIs require you to make a new request every time you need data. You can do a lot of the same things with both types of APIs, but you’ll find that some use cases are a better fit for one or the other. Let’s take a closer look at what makes asynchronous APIs different from synchronous APIs.

The difference between asynchronous and synchronous APIs

Synchronous APIs often use HTTP or HTTPS for transport, and HTTP is a unidirectional protocol. The client sends a request to the server, and then the server sends an HTTP or HTTPS response back. Asynchronous APIs tend to use bidirectional protocols like HTTP/2. When you use a bidirectional protocol, the client and server can maintain their connection, sending and receiving data for as long as they need to. You can think of it like this: when you make a synchronous request, you pull data from a server, but you can use an asynchronous request to ask the server to push the latest data to you.

When you send a request to an asynchronous API, your application can continue to process other instructions for your user while it waits for a response from the API server. This is different from a synchronous API, where the application won’t continue until it receives the response. If a resource, service, or datastore is not available immediately when you make the request, an asynchronous API can use a callback such as a webhook to notify your application when the resource is ready.

Not all API architectures fit neatly into the synchronous or asynchronous labels. For example, GraphQL can be considered synchronous because you send queries over HTTP, but it also supports asynchronous messaging using WebSockets with its subscription server. You can register with the GraphQL subscription server to receive asynchronous updates, with the added benefit of choosing exactly which fields you want included in the response. To see an example of a GraphQL API in Postman, check out the New Relic Nerdgraph GraphQL API Collection or our GraphQL examples workspace.

When to use an asynchronous API

Microservices are an excellent use case for asynchronous API requests. When you configure your application’s internal and external services to communicate with one another asynchronously, the services can send each other messages without necessarily being available at the same time, often by using a message broker to handle the requests. Instead of polling for new information, services can subscribe to the events that matter to them and receive push updates. Event-driven architecture relies on this publish-subscribe pattern of communication between services. This diagram shows an example of two event producers that share events with three services using the publish-subscribe pattern:

HTTP/2 also supports an unlimited number of messages over a single connection, so services can exchange data without having to initiate a new connection each time they make a request, as they do with HTTP. This makes them less likely to run up against a browser’s TCP connection limits. It also allows applications to communicate with the API in the background while executing other tasks, which leads to better performance and scaling for an application with a lot of user activity. The gRPC framework is a popular choice for internal services because it allows them to efficiently stream data to one another using structured data payloads.

Check out our recent Postman Level Up video about gRPC in Postman:

Asynchronous APIs are essential for bidirectional streaming. When you have a bidirectional connection, the client and server can continuously send messages to one another. HTTP/2 supports this type of connection by default. While it is technically possible to stream data over HTTP (usually known as chunking), it adds complexity on the client side and you can be slowed down by buffer limits and other issues. You will have a much better experience when you use HTTP/2 to stream data.

Example asynchronous API use cases

These are a few examples of applications that might use an asynchronous API:

Messaging
Social media
Mobile games
Banking

Better together

In many cases, applications benefit from using a combination of synchronous and asynchronous APIs. While asynchronous APIs can offer perks like faster communication, quicker response times, and reliable scaling, there are advantages to synchronous APIs. For example, if you need to make sure that requests are processed in a specific order, synchronous API calls are a better fit. Synchronous APIs are also less complex to set up, so they’re still ideal for a straightforward request-response pattern. If you’re not already using asynchronous APIs, you can start to incorporate them while keeping the functionality of your existing REST APIs.

Learn more about asynchronous APIs

Ready to dig into more asynchronous APIs in Postman? Check out these resources:

Technical review by Arlemi Turpault and Gbadebo Bello.

2 Ways to Access and Edit a Postman Element

Melinda Gutermuth — Wed, 21 Sep 2022 07:01:23 +0000

When you want to edit an element in a Postman workspace, whether it’s owned by your team, another team in your organization, or in a public workspace, the first step is to get access. If you already have the Editor role in the workspace that contains the element—whether it’s a collection, API, environment, mock server, or monitor—you can edit it directly. If you don’t have the Editor role, read on to find out how you can either gain access or propose edits without changing your access.

1. Request the Editor role

If the Postman element is in a workspace owned by your team or another team in your organization, the most straightforward way to get access is to request the Editor role. If you’re able to see the element but you see a lock icon next to its name, then you currently have the Viewer role. You need to ask someone who has either the Editor or Admin role in this workspace to elevate your access. Select the more actions icon, and then select Manage roles to begin your access request.

Viewing a collection in the Postman public workspace with the Viewer role

2. Create a pull request

In some cases, there might be an element you want to edit, but it’s outside the scope of your organization. If you want to edit an element that you don’t expect to get access to, like a collection in a public workspace, you can submit a pull request instead. Start by creating a fork of the element you want to edit. You can fork collections, environments, and flows, but you can only create pull requests for collections and environments.

To create a fork, you can either select the element and click the Fork icon, or you can select Create a fork from the more actions menu. The fork will be created in the workspace you choose. Keep in mind that your reviewers need to be able to view your fork to review your pull request, so forking to a public workspace makes that possible. If you’d prefer to edit your fork privately, you can fork to your personal workspace and move it to a public workspace later, when you’re ready to submit your pull request.

When you’re done making changes to your fork, use the more actions menu (click on three-dots icon) to select Create Pull Request , and then choose who you want to review it. They must have either the Editor or Admin role to merge your changes. The reviewers will receive emails letting them know about the pull request, and you’ll receive emails if they have comments or approve the request.

Watch and learn

Check out our recent Postman Level Up video that demonstrates these two methods for editing a collection:

Learn more about editing elements in Postman

Read about requesting access in the Postman Learning Center
Read about using version control in the Postman Learning Center
Watch Version Control for Collections: Postman Level Up
Read Collaborating in Postman Just Got Easier: Workspace Roles and More on the Postman blog
Read Introducing Environment Forking and Pull Requests on the Postman blog

The post 2 Ways to Access and Edit a Postman Element appeared first on Postman Blog.