DEV Community: Postman

Stop Exposing Secrets! Secure Your APIs in Postman Like a Pro

Bello Gbadebo — Fri, 07 Mar 2025 10:07:58 +0000

API security is crucial, as it directly impacts your business's success and safety. How well you secure your APIs can make or mar your product, and it is of utmost importance to spend time thinking about security.

I have seen developers work in Postman without properly securing their credentials, often leaving API keys exposed in shared environments or logging sensitive data in the console. For example, some developers unknowingly expose credentials when they make their workspaces public, allowing anyone to access sensitive API keys and tokens that are not properly stored.

In this post, I want to share some tips on how you can protect your data and API in Postman.

General Tips for Securing Your APIs in Postman

When working with APIs in Postman, taking proactive security measures is essential to prevent data leaks and unauthorized access. Implementing best practices ensures your credentials, tokens, and sensitive data remain protected. Below are some helpful tips on securely working in Postman.

1) The secret scanner is your friend

The Postman secret scanner is every developer's knight. It constantly scans your public workspaces and documentation for any exposed secrets. It checks your variables and environments, schemas, etc for exposed secrets and notifies all Team and Workspace admins via emails and in-app notifications.

Admins are given a link to view all exposed secrets in a dashboard and an option to immediately replace them with a placeholder using a single button click. This helps mitigate security risks faster.

If you do not replace exposed secrets in a timeframe specified in the email, the secret scanner will automatically replace this data with a placeholder for you. For example, authorization secrets can be replaced with {{vault:authorization-secret}}, or <AUTHORIZATION_SECRET>.

Pro tip 1 : Whenever you want to show an example of some sensitive data, always use placeholder data before making your Workspace public. Maintain a private fork of your collection that you can continue to work in even after making your base collection public.

There’s a lot more you can do with the secret scanner in Postman. You can mark alerts as ‘false positives’, ‘won’t fix’, etc.

Pro tip 2: Don’t ever ignore the secret scanner notifications. While there may be false positives, always check to ensure you’re not exposing anything and staying safe.

Learn more about the secret scanner here

2) Avoid secret keys in test scripts, headers, params, etc

When working with test scripts, depending on your workflow, some developers often prefer to make HTTP calls from pre-request scripts. Some HTTP calls require auth credentials, and these auth credentials can be easily exposed if you’re logging data to the console, passing data to a template for visualization, etc.

If you need to use sensitive data in your pm scripts, always first store them in a vault, environment, or collection variable, then programmatically access the data from storage.

In some cases, Postman actively checks for any sensitive data in your scripts and truncates them before logging to avoid being exposed.

Similarly, you should also be very careful when adding request headers, query/path parameters, etc. These are places where we’ve observed a lot of secrets being exposed. Our variable helpers make it easy to store data from those places into the vault or collection/environment variables. Simply highlight the value, and you will see a pop up that helps you store the data more securely.

Here’s a list of places to take note of when making a workspace public:

Request header
Collection/Environment/Global Variables
Query and Path Parameters
Authorization helpers (API Key, Basic, OAuth, etc)
Pre-request and Post-response scripts
Request body
URL bar
Postman Console

3) Keep your credentials local with Postman Vault

Some users worry about storing their credentials in Postman environments and variables because it could potentially sync with Postman cloud depending on how it is stored. While the Postman cloud is safe and secure, we always encourage everyone to store their API secrets in the Postman Vault.

Postman Vault is a local encrypted storage that only you can access. Data stored in the Postman vault are not synced with the Postman cloud and can only be accessed using a vault key. Your vault key can be stored in your system’s password manager or securely elsewhere.

You can limit vault secrets to specific API domains, and link them to external password managers like Hashicorp, Azure Vault, 1Password, etc if you intend to share credentials with your team. Vault credentials can be programmatically accessed in postman scripts similar to how you would access environments, and collection variables.

Pro tip: When working with authorization helpers in Postman. Always use the Postman Vault.

Learn more about Postman Vaults

4) Help your API consumers stay secure with Guided Auths

Guided Auth helps you onboard API consumers to your public APIs faster and more efficiently. When you set up Guided Auths for your public APIs in Postman, your API consumers get a step by step guide on how they can make their first successful API call as soon as they start typing your domain name in the URL bar.

They can easily set up different kinds of authentication(OAuth 2.0, Client Credentials, PKCE, etc) depending on how your guided auth is configured.

Learn how to setup Guided Auths here

Once you have guided auths setup, you can help your API consumers stay secure by choosing to store their credentials after a guided authentication step in Postman Vault. Vault secrets added using Guided Auth are inside double curly braces ({{ }}). The prefix vault: is appended to the vault secret's name, and a suffix is automatically appended with the authentication type.
e.g {{vault:postman-api-key:value}}

5) Current Values vs Initial Values

When using variables in Postman, it’s important to understand the difference between Initial Values and Current Values.

Initial Values are synced to the Postman cloud. If you share your collections, your variables become visible to your team and anyone who has access to that workspace.
Current Values are only stored locally on your machine and are not shared with others. This makes them ideal for storing sensitive API keys, tokens, or credentials.

Pro tip: Always ensure that sensitive data is stored as a Current Value to prevent accidental exposure. Use Initial Values to show examples of what the variable value could look like.

6) Authorization helpers are there to help

Postman provides authorization helpers that let you handle authentication securely without manually adding tokens or credentials in your request headers.

Instead of manually copying access tokens, use the OAuth 2.0 helper to automatically fetch and refresh tokens.
When using API keys, configure them in the authorization tab rather than adding them directly to request URLs.

7) Stop ignoring the warnings!

Postman does a great job at providing several warnings at different places when it suspects that something may be wrong. This warning can come as a UI popup, a push notification, an email, or status indicators on the UI depending on what it is you are trying to do. Always make sure you pay attention to these warnings and never ignore them.

It never hurts to double check to be sure you are not exposing any sensitive information.

Remember, your data will only be public if you make them public.

Pro Tip: When creating a new Workspace, always start with a Private or Team Workspace. Once you’re done making changes, review your work and then make it public. Ensure you always check thoroughly before changing a Workspace visibility to “Public”.

7) Enforce the Principle of Least Privilege(POLP)

Workspaces and Teams in Postman have Role Based Access Control(RBAC) integrated in them. We encourage teams collaborating in Postman to always give access and certain privileges to only those who need them. In a Postman Team, only individuals with super admin and community manager roles are allowed to manage all public elements. Therefore, we encourage you to only assign these roles to necessary people and have a standard review process in place for when Workspaces are being published to the public.

Learn more about managing public elements in Postman here

Final Thoughts

Securing your APIs is crucial, and Postman provides various tools to help you keep your secrets safe. By leveraging features like Postman Vault, the Secret Scanner, Guided Auth, Authorization Helpers, etc. you can significantly reduce the risk of exposing sensitive data.

Make sure you implement these best practices and regularly audit your Postman workspaces to ensure that your API security remains strong.

Got questions? Found any of this helpful? Let me know in the comments!

Happy coding and stay secure!
Cheers!

Note: This was originally posted on the Postman Community Forum

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.

Postman Terms vs GitHub Terms

Johannes Nicolai — Wed, 06 Dec 2023 22:48:24 +0000

I am an open source enthusiast who recently joined Postman and previously worked at GitHub. Many Postman concepts around organization, discovery, collaboration, users, and permissions are quite similar to GitHub’s, but they are referenced with different terms. We noticed in discussions with our community that it helped accelerate adoption of both platforms when we presented a short comparison of the concepts and their terms. This blog post builds on the first iterations of simple comparison tables in my Postman and GitHub profiles. Read on to learn more.

Organizing users

Postman team vs. GitHub Enterprise account

One of the key differences between Postman and GitHub is the concept of a team. In Postman, a team encompasses all users and workspaces within an entire company or larger business unit. It can potentially have thousands of workspaces and users (groups). GitHub uses the term "Enterprise Account" to refer to a similar concept, which encompasses all of the users and repositories within multiple organizations. If you are looking for a way to group a subset of users to form a “team of users” in Postman, have a look at user groups.

Postman user group vs. GitHub team(s)

In Postman, user groups are defined at the Postman account level and allow you to group users across multiple workspaces. User groups are a logical grouping of users based on a company's or organization’s needs. For instance, this grouping could be based on a people team, project, responsibility (i.e., an admin group), or some other logical organization of users.

In GitHub, teams are defined one level below (i.e., at the organization level) and govern access to the repositories of the organization to which they belong. GitHub teams can also be used to group people based on their responsibility or interest, but if you like to use teams across GitHub organizations, you need to duplicate them.

Postman team member vs. member of a GitHub Enterprise account/org member

A team member in Postman refers to a user who is part of a specific team within the organization. In GitHub, an equivalent concept is a member of an enterprise account or an organization member in a freestanding GitHub organization. A GitHub team member would only belong to one organization.

Postman Workspace Admin vs. GitHub org owner

A Workspace Admin in Postman has administrative privileges within a workspace. In GitHub, the equivalent role is an organization owner, who has full administrative control over the organization and its repositories.

Postman Super Admin vs. GitHub enterprise owner

In Postman, a Super Admin has the highest level of administrative privileges and can manage teams and workspaces across the organization. In GitHub, the equivalent role is an enterprise owner, who has full administrative control over the enterprise account.

Managing access

Postman workspace vs. GitHub orgs

Both Postman and GitHub provide features for organizing content and enabling collaboration. Workspaces in Postman are used to collaborate on collections, APIs, mock servers, monitors, environments, and Flows. In GitHub, organizations serve a similar purpose for managing repositories.

Postman public workspaces vs. GitHub orgs with public repositories

Postman allows you to create public workspaces that include publicly accessible content. Public Postman workspaces are comparable to GitHub organizations that contain only public repositories that are accessible to anyone.

Postman team workspaces vs. GitHub orgs with internal repositories

In Postman, team workspaces are accessible to any member of the same account or Postman team. In GitHub, this corresponds to internal repositories and standalone organizations that have their default access/base permissions set at least to “Read.” For Postman teams that represent multiple business units or larger parts of an organization, all elements within a team workspace are potentially visible to thousands of people. This is great from an InnerSource and company knowledge sharing perspective. In the cases where the “need to know” principle applies, consider using private workspaces and assign the groups of people that should have access.

Postman private workspaces vs. GitHub orgs with base permissions set to “None”

The word “private” in private workspaces does not imply that these workspaces can only be accessed by their creators (that’s what personal workspaces are for). It just means that not everybody in your Postman team will have read access by default (which is the case for team workspaces). You can use private workspaces to provide selective access to a group of people—either individually or by assigning Postman user groups to the workspace. You can also open the workspace up for entire business units.

In GitHub, most organizations within an enterprise team are configured similarly, with base permissions set to “None,” so that access rights are assigned by GitHub teams (which are similar to Postman user groups).

Postman Partner Workspaces vs. GitHub repositories with invited external collaborators

Postman allows you to create Partner Workspaces and share their contents with external collaborators outside the core team. In GitHub, you can invite external collaborators to specific repositories.

Postman personal workspaces vs. GitHub personal repositories

In Postman, users can create personal workspaces that can only be accessed by their creator and Super Admins of the same team. If a user leaves the enterprise team, they lose access to their personal workspaces, as well. Similarly, GitHub allows users to have personal repositories within their personal namespace that only they can access.

Postman collection access keys vs. GitHub Gists

Both GitHub and Postman provide methods to share access to source code or collections to anonymous users with a secret link. In GitHub, that functionality is called a secret gist. In Postman, it originally was possible to share private collections with the world via Collection JSON Links, which have been deprecated. Now, Postman users can use Collection Access Keys, which provide better control over the expiration date, as access gets revoked if the key’s creator loses access. Postman Enterprise teams can also deny public link creation completely and revoke any existing links.

Postman permissions vs. GitHub permissions

Postman Enterprise and GitHub both provide the ability to define permissions on multiple levels. Postman team roles on the highest level correspond with GitHub enterprise account-wide settings. Those roles and settings also define who can invite new users to the team or enterprise org, who can change the visibility of workspaces or repositories, and whether ordinary users can create public workspaces or repositories. Postman workspace roles compare best to GitHub organization default access permissions, and Postman permissions on individual collections, APIs, or mock servers (element-based roles) correspond to repository-specific permissions that a team or collaborator has on GitHub.

Managing collaboration and discovery

Postman fork vs. GitHub Fork

Postman allows you to fork collections, environments, and flows. It is possible to fork within the same workspace and into different workspaces. You can also have as many forks in the same workspace as you like, which makes fork-based collaboration easier. Furthermore, forks in Postman do not have to have the same visibility as the parent, and they will continue to exist if the parent gets deleted. You can keep your forks up-to-date by pulling changes from the base collection or environment, which is similar to how GitHub pull requests work.

Postman pull request vs. GitHub Pull request

Native pull requests in Postman require the reviewer to have at least “View” permissions in the fork, as the suggested changes are not created within the same workspace, as they are in GitHub. Postman pull requests also work for changes to environments. For API development, it is also possible to use native GitHub pull requests within Postman.

Postman comments vs. GitHub comments

In GitHub, you can comment on pull requests, individual source code lines in pull requests, and commits. Within Postman, you can comment on collections, requests, request parameters, folders, and individual lines in API definitions, test cases, and pre-request scripts. Both platforms support Markdown and tagging users to get their attention.

Postman tags vs. GitHub repository topics

In Postman, you can tag collections, APIs, and workspaces to make them easily discoverable within your workspace, your private API network, your team, or even the Public API Network. In GitHub, you can assign topics to repositories to make them more discoverable within the same organization or across all of GitHub.

Postman published documentation vs. GitHub Pages

Postman documentation can be published to a website hosted by Postman or to your own custom domain. Similarly, GitHub provides the ability to turn your repository content into a web page hosted on GitHub Pages with support for your custom domain, as well.

If you’d like to see what is possible with custom branding and domains, check out Imgur’s published Postman Collection.

“Run in Postman” button vs. GitHub Codespaces

If you have your own API or developer portal and you’d like to provide a lightweight way to test drive your APIs or source code in a live execution environment, you can generate a Markdown or HTML snippet with a “Run in Postman” button, or point to a GitHub Codespace of the corresponding GitHub repository.

PayPal’s developer portal includes a great example of how to use a “Run in Postman” button to let anybody try out your API within less than a minute without previous knowledge.

We love feedback!

We hope that these comparisons can help you to more easily adopt Postman and GitHub—and use them together. If you have any feedback or additional mapping suggestions, please open a pull request in our GitHub repository.

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.

Powering home automation with WebSocket APIs

Joyce Lin — Thu, 06 Jul 2023 15:08:43 +0000

In Part 1 of this series, we learned about the WebSocket protocol and how to set up our own WebSocket server in Node.js. Next, let’s explore how to use a public WebSocket API to access smart devices around a connected home.

REST and WebSockets for a connected home

When it comes to transmitting data in a connected home environment, both REST and WebSockets are commonly used protocols, but they have different characteristics and use cases.

REST follows a request-response pattern, where a client sends a request to a server, and the server responds with the requested data. This is useful for accessing and controlling smart devices and services, and works well for scenarios where data updates are not required in real-time. For example, you could use a REST API to turn on a smart light.

On the other hand, WebSockets enables bidirectional communication between a client and server, enabling real-time data transmission. This is useful for applications that require continuous data updates, such as real-time monitoring of sensor data and displaying live dashboards. For example, you could use a WebSocket API to continuously monitor the temperature in a room over a persistent connection.

In the next section, let’s take a look at a popular home automation platform that provides both REST and WebSocket APIs.

Home Assistant for home automation

Home Assistant is a popular open-source home automation platform that lets you control and monitor smart devices from different brands using a unified interface. Instead of using separate applications to control the kitchen lights, thermostat, and other connected devices all manufactured by different producers, you can manage almost everything from a single Home Assistant web dashboard running on a Raspberry Pi or other dedicated server within your local network.

Home Assistant progressive web application running at http://homeassistant.local:8123

Home Assistant is ideal for DIY smart-home tinkerers because it supports a wide range of integrations and protocols, allowing you to customize automation scenarios based on events, schedules, and sensor readings.

Next, let’s take a look at Home Assistant’s WebSocket API.

Home Assistant WebSocket API

In addition to a REST API , Home Assistant also contains a WebSocket API to stream information. To learn how to authenticate the WebSockets connection and send saved messages to the Home Assistant server, follow along with this step-by-step tutorial, watch the video, and reference the sample collection.

Using a long-lived token, you can use Postman to establish a connection with our Home Assistant server running locally, and then send and receive messages using the WebSocket API.

Receive a stream of information when the state changes on any device connected to Home Assistant

You can also configure your own Saved Messages to create your own customized themes and sequences.

Saved messages to replay common scenarios

Home Assistant also provides a REST API. Explore Home Assistant’s WebSocket and REST APIs side-by-side in Postman to better understand the differences between the two protocols.

Additional resources

You can work in Postman using different API patterns and protocols. Check out these Postman resources to learn more about WebSockets:

Browse the Program smart lights public workspace for APIs from other providers, such as Philips Hue and Elgato, to automatically control smart lights in your home or office. And let us know in the comments below what kind of projects you want to learn about, and what you’re doing with WebSockets.

The post Powering home automation with WebSocket APIs appeared first on Postman Blog.

Create a REST API with PHP and Laravel

Greg Bulmash 🥑 — Tue, 06 Jun 2023 18:39:01 +0000

PHP came out in 1995, just three weeks after Java. Today, both remain in the top ten most popular languages. With PHP’s general ease of use, options for how to use it abound. Yet, not every PHP tutorial is created equally. That’s why we put together this beginner-friendly Postman Quickstarts tutorial on building a REST API with PHP. We’re using what we think is a straightforward framework for this purpose: Laravel.

Laravel is a popular PHP web app framework that comes with a variety of built-in tools and features for building APIs. In this tutorial, we will be creating a simple API that allows users to add and retrieve data.

Before we get started…

Double check that you’re ready to write in PHP. Only a basic familiarity is needed for this tutorial, and PHP has a notoriously flat learning curve for new users—we encourage you to try at any skill level.

Next, confirm that the following are installed:

Git (Required)
PHP (Required)
Composer (Required)
Homebrew (only for Mac)

If you want step by step instructions for installing any of the above, refer to the full Laravel API quickstart guide at Postman. Plus, you’ll also want to open up your favorite code editor. Now, let’s get started!

Step 1: Start your Laravel project

Scaffold your Laravel project

Before we can write any code, we need to scaffold a Laravel project. Thanks to Composer, this is relatively simple. Open a terminal and navigate to the directory where this project will live. Enter the following command in the terminal:

composer create-project laravel/laravel laravel_project

This could take some time. There are tens of megabytes to download and install.

When it's finished, you will have a project folder named laravel_project.

Give it a test

Navigate into the laravel_project folder and enter the following command in the terminal:

php artisan serve --port=8080

This will launch your project at http://localhost:8080. Change the port to something else if you already have a process using the port. When it's running, visit the URL. It will return this homepage.

Note down in the bottom right, you'll see the Laravel and PHP version numbers. If you're looking for tutorials, finding ones for Laravel and PHP that are as close to those versions as possible will help minimize problems.

Let's move on to adding an API.

Step 2: Build an API

Create the route

This will create a public API with no authentication.

Open routes/api.php in your Laravel project directory in your editor. Add the following code at the end:

Route::get('/hello', function () {
  return "Hello World!";
});

This adds the /api/hello endpoint and returns "Hello World" in plain text to a GET request.

Note how the endpoint was prefixed with /api by Laravel.

Next, let's call this endpoint in Postman.

Step 3: Try your first endpoint

To test this in Postman, open your personal workspace and start a collection. Name it "Laravel QuickStart" or something else you prefer.

Once it's created, select Add a request to get started.

Set the request URL to localhost:8080/api/hello and make sure your Postman Desktop Agent app is running on your machine to prevent any CORS issues while testing locally.

Select Send and the response section below the request section will show a response of Hello World! in plain text with a 200 OK response code.

Congratulations. You created your first API endpoint in Laravel and successfully called it with Postman.

Next, let's make a simple POST endpoint for fun.

Step 4: Add a POST endpoint

Go back to your routes/api.php file and add the following:

Route::post('/reverse-me', function (Request $request) {
  $reversed = strrev($request->input('reverse_this'));
  return $reversed;
});

This adds a POST route for the endpoint api/reverse-me. It will reverse a string you pass in the body of the post with the parameter name reverse_this.

Let's try this in the next section.

Step 5: Try your POST endpoint

Return to your Laravel QuickStart collection in Postman and add a request. Name it "Reverse" and follow these steps:

Set the request type to POST.
Set the endpoint to localhost:8080/api/reverse-me.
Select the Body tab.
In the top dropdown menu in the tab, select x-www-form-urlencoded.
Add a parameter of reverse_this with the value of esrever. That's "reverse" already reversed so the return value will be easy to read.
Select Send

The API will return the string reverse in plain text. Congratulations! You’ve created a REST API with PHP and Laravel.

Summary

In this blog post, we explored how to create a simple PHP-based API with the Laravel framework. We created both GET and POST API endpoints and used Postman to test those endpoints. By following this tutorial, you should now have a solid understanding of how to create a basic API with Laravel and how to test it using Postman.

Going further…

If you want to deepen your knowledge of Laravel and Postman, try these exercises:

Dive into the Laravel 10.x documentation to add a controller for handling more complex requests and/or add a model to connect a database.
Review the Laravel 10.x error handling documentation to learn best practices for error-handling in Laravel, such as what might happen if someone submitted a binary file instead of a string to your string-reversing endpoint.
Explore the Postman testing documentation and write a test on the POST request to make sure the reverse_this string is being reversed properly.

Check out Postman Quickstarts for more step-by-step guides like this one. If you’d like to contribute your own, head over to the Postman Quickstarts repo on GitHub.

Build a successful API by understanding user personas

Jan Schenk (he/him) — Tue, 16 May 2023 16:16:41 +0000

This article has been written by Bruno Pedro on the Postman Blog.

Postman Open Technologies Knowledge Base is a new project with the goal of providing insights from a vast amount of information about APIs available on the internet. One of the project’s objectives is to provide an API that consumers can use to retrieve information from the Knowledge Base. The result? As part of my work on the Postman Open Technologies team, I have been building the Knowledge Base API.

I’ve naturally started by following our Postman team’s internal API Design Playbook. The playbook is a series of steps that help anyone building an API come up with a solution that meets the needs of consumers. (Stay tuned for when I make this publicly available!) The API design steps covered by the playbook are strategy, definition, validation, and finally, specification. I started the design of the Knowledge Base API with the strategy step, where the goal is to document why the API should be built. The output of the strategy step consists of findings and evidence that back the importance of building the API.

Finding evidence that the API should be built can be done by understanding and analyzing potential consumers. And that’s precisely what I have done: I have identified the user personas that can benefit from using the Knowledge Base API:

Technical researchers
API designers
Product managers
Technical architects

How do you identify user personas for an API?

To identify the four user personas, I engaged with people from each of the categories in a series of interviews. I wanted to understand what their work was like and what challenges they were facing. I also wanted to validate my initial hypothesis that they would be interested in the Knowledge Base API I was designing. Not only was I able to confirm most of my assumptions, but I also enriched the information I had with feature requests. So, for example, a product manager revealed that it would be interesting to get information about API design trends. A researcher gave importance to knowing the provenance of the data used in the Knowledge Base.

I then used the information from the interviews to create my catalog of user personas. For each user persona, I have identified their jobs-to-be-done (JTBD), the tools and services they use, their work-related challenges, the benefits they would get from using the Knowledge Base, and their potential behaviors when using the API. These attributes helped refine the user personas and will help me design the different elements of the API once I get to that stage.

At this point, it’s worth remembering that user personas are fictional characters representing a specific type of person who will be using the API. Each persona has unique characteristics, such as JTBD, benefits, behaviors, and challenges. For example, a technical researcher may be interested in using an API to gather data for academic research. In contrast, product managers may be looking for an API that helps them analyze customer behavior and preferences. The important thing is that you’re able to identify a cohort of users with each of the personas.

Benefits of knowing your audience from the start

Let’s get back to my journey designing the Knowledge Base API. With all the user personas identified and documented, I could then start focusing on defining other attributes of the API. By knowing the tools each persona uses, I was able to identify the best architectural style for the API. With the benefits documented for each persona, I could define the API capabilities. JTBDs and behaviors helped me identify the API resources and operations. Altogether, the different attributes of user personas can continuously inform how I design an API that reflects what potential consumers need. And that is critical to making an API successful.

In summary, APIs explicitly designed for targeted users are more likely to be adopted. Those APIs directly address the real-world problems or goals of users. Aligning APIs with user personas’ needs and behaviors from the start will yield better outcomes than assuming what is best and hoping that users will engage.

The post Build a successful API by understanding user personas appeared first on the Postman Blog.

10 reasons why you have to exceed at documenting

Jan Schenk (he/him) — Wed, 10 May 2023 07:18:32 +0000

I’m leading Postman’s Open Technologies Program Office — our open source program office (OSPO). My team consists mainly of open source contributors, and our parent org, Postman Open Technologies, is an incubator for API tech and a strategy think tank. There’s a bunch of high-profile industry experts that I work with and for, and I’m constantly switching between impostor syndrome and delusions of grandeur to change the world.

At a recent Postman Open Technologies team meeting, I gave a very general direction in saying that we have to be the team that is known for documentation and that we need to document everything individually as well as in a team effort. While there was more context, like our collaboration with the product teams, it is also a general recommendation that I give to myself as well as others in our industry — especially in these fields of work: engineering, OSPOs, and developer relations.

But first, let’s define the term “documentation.” In the context of this blog post, documentation includes external as well as internal technical documentation, blogging, sharing knowledge on social networks, demos, how-to articles, instructions, conference sessions, webinars, podcasts, wikis, infographics, flow charts, and the like.

I understand how easy it is to get lost in responsibilities in today’s fast-paced world. But while you won’t be immediately rewarded for writing documentation like you are for writing code, setting up a process, or resolving an issue, creating good documentation is about showing compassion to those around you as well as your future self. Its impact is mid- and long term, but needs prioritization now.

My top 10 reasons why being great at documentation is key to success

You should be known as the person who exceeds at documenting because:

Documenting makes you a better coworker and collaborator. Creating good documentation reduces frustration, lowers the level of collaboration anxiety, and makes previous decisions more understandable.
Documenting increases your value. It increases your value as a professional and makes you less expendable. Letting go of a person or a team that built a good part of the internal knowledge hurts. Hiring someone who is known for building persisting knowledge is easier to justify.
Documenting helps build your personal brand. Coming across the same author name over and over again when doing research makes you a subject expert. Add on top a few more measures,—like community engagement, mentoring, public speaking, whatever you choose—will greatly help your brand.
Documenting builds internal visibility. Being able to refer to something that you’ve written is easier than vaguely repeating what you have said or commented on a team meeting. Colleagues are more likely to give credit if it’s easy to do.
You can slice and dice into content creation. Once you’ve started documenting things, you can slice and dice it for content creation. Producing a video, writing a podcast narrative, preparing a talk, or inviting people with similar or differing opinions to a panel is way easier than starting from scratch. It also helps you find a red thread for your storytelling, which is another item on this list.
Documenting helps internalize your knowledge. And identify caveats. Repetition, that’s how the human brain works. Writing something down is exactly this. When your fingers are slower at typing than your brain is at processing information, you’re forcing it to repeat the same thing over and over again. That helps you either internalize findings or helps you find catches and bugs in your thinking.
Documenting makes your knowledge persist. The most obvious one, but also the most ignored point on my list. Have you ever come across a written piece and thought, Hey, that’s good knowledge, I’m glad someone else wrote it down! only to realize it was you two years ago? We forget, and that’s even part of our learning process. Storing information is not only something you do for others but also for yourself. And even if you don’t regularly update your content, it will be useful for a certain amount of time and maybe even beyond. (Disclaimer: This is not a good excuse for not keeping your documentation up to date!)
Documenting saves time. Were you assuming the opposite, that writing documentation eats up a lot of time? Have you ever felt like repeating yourself? That’s probably because you did. When you write documentation it saves you from the tedious work of repeatedly explaining to others. When you’re spending the third time explaining something, your time would have been better spent writing it down. You could still have that discussion with your peer, but you’d have it on a different level.
Documenting helps avoid the awkwardness of having to ask. It’s not only you feeling bored about explaining the same old thing a third time this week. It’s also them feeling bad about wasting your time. Coworkers might hold back from asking you because they feel your time is too precious. This hinders collaboration.
Documenting makes you better at storytelling. The bigger picture is something that you will be asked for. Being able to not only provide facts and figures but also develop a narrative and make the numbers stick to someone’s mind is priceless.

It’s important to note that while I say “good documentation,” I don’t ask for “excellent” or “outstanding.” That’s not because I think that nothing will ever be perfect; it’s because documentation doesn’t always have to be pristine. Often enough, “average documentation” does the job and is a legit compromise between effort and benefit.

Whenever you consider prioritizing documentation, which includes internal as well as external content creation, you definitely should always answer: “Yes, I will.”

The post 10 reasons why you have to exceed at documenting appeared first on Postman Blog.

Your Shortcut to Becoming a Contributor in Google Summer of Code

Jan Schenk (he/him) — Thu, 23 Mar 2023 07:48:30 +0000

Here's a shortcut to your participation in Google Summer of Code. Or is it? The following points are the absolute must-have-dones for a successful application. And yes, please do apply. All former participants that I have talked to say it has been more than worth their time.

📖 Take 20 minutes to read into GSoC. What it is and terms and conditions. You don't need to know every detail, but you should have a basic understanding of how it works.
https://summerofcode.withgoogle.com/

📁 Check out our suggestions for projects. If you don't find anything in there, don't give up. Browse other organisations. Open Source needs you, no matter where you eventually find your sweet spot. But we at Postman are definitely the best place for APIs. https://github.com/postman-open-technologies/gsoc-2023/issues

🎙️ Get in touch with a mentor on the project(s) of your choice. You can only apply to 3 projects, so you better know who you are committing to work with. How to find a mentor? Identify them on the issues and dedicated repos, and hit them up here or on the projects' channels (could be Slack or Discord or a forum. You will learn this from the issue/repo). Ask them if they think your skillset matches the project.

🧪 Try yourself out. There will be micro-tasks and first issues on the repo. This will help you make your first steps in Open Source as well as understand if this project is a fit for you.

🪪 Register and apply on the GSoC website. You can modify your application until April 4. Don't worry if you don't have all the details ready yet. But start with something that doesn't make mentors ignore your submission (like only uploading a CV instead of an application pdf, or skipping on the details of your proposal). Expect 1h and likely more for this step. But the earlier you get to actually submitting your proposal, the better, as it creates better visibility.

👷 Continue to update your application, and stay in touch with the mentors. Engagement in the existing community is key.

🏆 You got this! 🏆

Boosting Your Personal Productivity - Life Hacks

Jan Schenk (he/him) — Tue, 21 Mar 2023 10:49:20 +0000

I asked my Postman colleagues what their secrets to an efficient and productive day are. Here’s their tips on how to increase your productivity. Not everyone is the same, so some things may work for you while others won’t. That’s ok. You do yours.

The Shultz Hour - Reserving one hour per week to zone out in a controlled manner.

Morning Pages - Habit of writing down your stream of consciousness first thing in the morning.

Calendar blockers for catching up with Slack, email. But also for lunch. And more.

Focus time playlists - using specific music to get into the flow. Many music streaming platforms have them under the name of e.g. Deep Focus (Spotify), Pure Focus (Apple Music), White Noise (different noise colors work for different kinds of people) or similar.

Calendar Bot/AI - look into reclaim.io Geekbot - an assistant on Slack to manage your day and keep track of what you do. Can integrate with your calendar.

Geekbot - an assistant on Slack to manage your day and keep track of what you do. Can integrate with your calendar.

Physical barriers - One colleague mentioned uninstalling Slack from the laptop and only have it on their iPad that is on another table. Other barriers can include: No meetings on the laptop. Chatting and doing calls happen on a separate place. What a bold move!

Work equipment - A good keyboard and mouse (or trackpad, graphic tablet, other pointer device) can enhance your productivity quite a bit. So does a good ergonomic chair. Also habits: Coding, writing, or any focus work happen with a proper chair and table.

Habits - Another colleague mentioned that a morning routine only gets them started. And for them that even includes a game of chess.

Running - Lots of folks mentioned that integrating running into their weekly (or daily) schedule improved their stress level and helped them balance.

Peripatetic meetings - Take a walk while you meet. This doesn’t require the physical presence of your meeting partner(s). But it helps making it clear to them that you do this.

Self-awareness - Finding out how often you pick up your phone during the hours that you thought you’d be focused helps you learn about yourself. Same is true for screen time and received notifications. For me it was 41 pickups, 1h 46m screen time and 116 notifications. Today, at 11:30am.

Try out what works for you and let us know here. Or share your own productivity hacks in the comments.

Join Postman for Google Summer of Code

Jan Schenk (he/him) — Thu, 02 Mar 2023 11:50:21 +0000

To all folks new to Open Source but interested in APIs:

Google Summer of Code is around the corner and Postman was able to join the group of mentoring orgs. This means we're offering a bunch of projects from OpenAPI, JSON Schema, AsyncAPI and Collection Format to work on as a newcomer to Open Source. Never contributed before? This is for you. You're an eager learner in the field of API technologies? Come join us. You want to contribute to the awesome work API Specifications are doing every day? Hello!

Google Summer of Code, GSoC, is an established summer school for people new to contributing to Open Source. You don't have to be a student to participate. Your commitment is to spend 175 or 350 hours (depending on the project you choose) coding to extend an existing Open Source project. There's suggestions on what to develop from all kinds of organisations, but of course, Postman is the coolest to choose. Why? Because we care for APIs, which are the underpinning of all the tech out there. If you understand the API lifecyle and its impact in our modern world, you can literally work everywhere.

So throw your summer plans overboard, and apply for a GSoC contributor in 2023. We'd love to work with you.

There's only two things you need to know and do until March 20, 2023

1) Move over to https://summerofcode.withgoogle.com/ and learn about the program. If you're accepted, you'll earn $$ for contributing to Open Source. How cool is that.

2) Visit https://github.com/postman-open-technologies/gsoc-2023, choose from our list of projects and show us that you can be that awesome contributor you always wanted to be.

Don't wait too long!

We're looking forward to seeing you drop into our repos issues. (Hint: that's GitHub slang for visiting our repositories, heading over to the Issues section and start commenting and letting people know what your ideas are. No worries, you'll learn it all during this summer!)

Yours truly
Open Source Program Office at Postman <3