登录查看更多内容

What is the best way to conduct an API design review?

由人工智能和领英社区提供技术支持

API design is a crucial aspect of software development, as it defines how different components interact and exchange data. A good API should be clear, consistent, reliable, and easy to use. However, designing a good API is not easy, and it requires feedback from multiple stakeholders, such as developers, users, and testers. How can you conduct an effective API design review that ensures quality and alignment with your goals? Here are some tips to help you.

在这篇协作文章中查找专家回答

由社区从 4 条内容中精选。了解更多

1 Define the scope

Before you start the review, you need to define the scope of the API design. What are the main features and functions of the API? What are the use cases and scenarios that the API should support? What are the non-functional requirements, such as performance, security, and scalability? Having a clear scope will help you focus on the most important aspects of the API design and avoid unnecessary or irrelevant details.

添加您的观点

Roberto Alvarado

Freelancer Developer en Freelancer
举报内容
Según mi experiencia, es muy, muy importante devolver la solo la información necesaria. Es muy comun que algunos desarrolladores piden que se devuelva todas las columnas de nuestra tabla de dominio en el response del API. Pero, recuerden, si tenemos el ciudaddo de especificar SOLO los atributos a exponer o devolver, nuestra API será mucho mas rápida, pues esta devolviendo solo que se necesita, y con esto último estaremos protegiendo la integridad de la informacion de nuestro dominio.

已翻译

赞
Jeffrey Ramirez Chumbes

Android Developer / Web Developer
举报内容
Primero antes que nada se debe definir el tipo de API que se va a dise?ar si es enfocada a data no sensible o por el contrario es un API Transaccional, Segundo en base al primer punto se debe gestionar el API en base a los requerimientos de Arquitectura(Casos de Uso, Módulos, Etc) Tercero una vez ya definido lo anterior mencionado se debe decidir que tipo de Seguridad se va a manejar(ApiToken, Session, Etc) Finalmente una vez ya definido ello el api se debe enfocar en ser lo mas concreto posible

已翻译

赞

2 Choose the format

When conducting an API design review, there are different formats to choose from depending on your preferences and resources. For example, you can create a document that describes the API design to share with reviewers, or you can write some code to implement the API design. Additionally, you can present the API design in a live session. Each format has its advantages and disadvantages; document review is more formal but may take longer, while code review is more practical but may require more coding skills and tools, and live review is more dynamic yet may be harder to schedule and record. Ultimately, you should choose a format that best suits your needs and context.

添加您的观点

Jeffrey Ramirez Chumbes

Android Developer / Web Developer
举报内容
Según mi experiencia la mayoría de los casos esto se define en base al usuario final del api ya que este es el que a fin de cuentas va a consumir nuestra API

已翻译

赞

3 Select the reviewers

The next step is to select the reviewers who will participate in the API design review. The reviewers should be people who have a stake in the API design, such as developers, users, testers, or managers. The reviewers should also have different perspectives and backgrounds, such as domain knowledge, technical expertise, or user experience. The reviewers should also be willing and able to provide constructive and honest feedback, without being biased or hostile.

The number of reviewers depends on the complexity and the scope of the API design, as well as the format of the review. Generally, you should aim for a balanced and diverse group of reviewers, but not too large or too small. Too many reviewers may lead to confusion and inconsistency, while too few reviewers may lead to gaps and blind spots.

添加您的观点

Jeffrey Ramirez Chumbes

Android Developer / Web Developer
举报内容
Una vez en el trabajo liberaron el api al público en general lo cual genero un montón de problemas desde intermitencia hasta problemas de seguridad . Desde entonces es mejor solo pedir feedback de la gente que este o estará involucrado en el API

已翻译

赞

4 Prepare the materials

To prepare for an API design review, you need to define the scope, choose the format, and select the reviewers. Additionally, you should provide the materials for the review, such as the API design (in a document, code, or presentation), a summary of goals and requirements, a list of questions or topics to focus on, and a feedback form or template. It's best to share these materials with the reviewers in advance so they have time to review them and prepare their feedback. You should also provide instructions on how to access and comment on the materials, as well as a deadline and expectations for the feedback.

添加您的观点

5 Conduct the review

The final step is to conduct the API design review, according to the format that you have chosen. During the review, introduce the API design and its purpose to set the tone and objectives. Explain the API design and rationale behind it to inform and educate the reviewers. Solicit feedback from them to gather their opinions and suggestions. Address their feedback to acknowledge and respond to comments and questions. Summarize the feedback and next steps to close the review and plan actions. The review should be respectful, constructive, and collaborative, with an emphasis on improving the API design and solving problems. Additionally, it should be timely, concise, and relevant without going off-topic or wasting time. Documenting, recording, or archiving the review is also important for future reference and accountability.

添加您的观点

6 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?

添加您的观点

Software Design

+ 关注

给文章评分

我们借助人工智能创建了此文章。您认为这篇文章怎么样？

很棒不太好

举报此文章

查看全部

What is the best way to conduct an API design review?

1

2

3

4

5

6

1 Define the scope

2 Choose the format

3 Select the reviewers

4 Prepare the materials

5 Conduct the review

6 Here’s what else to consider

Software Design

给文章评分

感谢您的反馈

更多Software Design相关文章

更多相关阅读内容

What is the best way to conduct an API design review?

1

2

3

4

5

6

1 Define the scope

2 Choose the format

3 Select the reviewers

4 Prepare the materials

5 Conduct the review

6 Here’s what else to consider

Software Design

给文章评分

感谢您的反馈

查看其他技能