Convenciones de nombres

Para proporcionar una experiencia del desarrollador coherente entre varias API y durante un tiempo prolongado, todos los nombres que usa una API tienen que ser de la forma siguiente:

  • sencillo
  • intuitivo
  • coherente

Esto se aplica a los nombres de interfaces, recursos, colecciones, métodos y mensajes.

Debido a que muchos desarrolladores no son hablantes nativos de inglés, uno de los propósitos de estas convenciones de nomenclatura es garantizar que la mayoría de los desarrolladores pueda comprender una API con facilidad. Para lograrlo, se incentiva el uso de vocabulario simple, coherente y breve a la hora de nombrar métodos y recursos.

  • Los nombres que usan las API tienen que ser correctos en inglés estadounidense. Por ejemplo, “license” (en lugar de “licence”), “color” (en lugar de “colour”).
  • Por cuestiones de brevedad, se podrían usar formas cortas o abreviaturas aceptadas con normalidad. Por ejemplo, se prefiere usar el término API en lugar de interfaz de programación de aplicaciones (por sus siglas en inglés).
  • Cuando sea posible, usa terminología intuitiva y familiar. Por ejemplo, cuando describas la operación de eliminación (y destrucción) de un recurso, es preferible usar “delete” y no “erase”.
  • Usa el mismo nombre o término para el mismo concepto, incluso en los conceptos compartidos entre las API.
  • Evita la sobrecarga del nombre. Usa nombres distintos para conceptos diferentes.
  • Evita usar nombres demasiado generales que son ambiguos dentro del contexto de la API y del ecosistema más amplio de las API de Google. Pueden provocar una interpretación errónea de los conceptos de la API. En su lugar, elige nombres específicos que describan con precisión el concepto de la API. Esto es muy importante para los nombres que definen elementos de primer orden de la API, como los recursos. No hay una lista definitiva de nombres que se deben evitar, ya que se debe evaluar cada nombre en el contexto de otros nombres. Instancia, información y servicio son ejemplos de nombres que generaron problemas. Los nombres elegidos deben describir el concepto de API con claridad (por ejemplo: ¿instancia de qué?) y distinguirlo de otros conceptos relevantes (por ejemplo: ¿“alerta” significa la regla, la señal o la notificación?).
  • Analiza con cuidado el uso de nombres que podrían entrar en conflicto con palabras clave en lenguajes de programación comunes. Se podrían usar esos nombres, pero es probable que activen análisis adicionales durante la revisión de la API. Úsalos con buen juicio y moderación.

Nombres de productos

Los nombres de productos se refieren a los nombres de productos de las API usados por marketing, como API del calendario de Google. Las API, las IU, la documentación, las Condiciones del Servicio, los resúmenes de cuenta, los contratos comerciales, etc. deben usar los nombres de productos de forma coherente. Las API de Google deben usar nombres de productos aprobados por los equipos de marketing y productos.

En la tabla a continuación, se muestran ejemplos de todos nombres de API relacionados y su coherencia. Consulta más abajo en esta página para obtener más información sobre los nombres respectivos y sus convenciones.

Nombre de la API Ejemplo
Nombre del producto API del Calendario de Google.
Nombre del servicio calendar.googleapis.com
Nombre del paquete google.calendar.v3
Nombre de la interfaz google.calendar.v3.CalendarService
Directorio de origen //google/calendar/v3
Nombre de la API calendar

Nombres de servicios

Los nombres de servicios tienen que ser nombres DNS con sintaxis válida (según la RFC 1035) que se puede resolver en una o más direcciones de red. Los nombres de servicios de las API de Google públicas siguen el patrón: xxx.googleapis.com. Por ejemplo, el nombre de servicio del Calendario de Google es calendar.googleapis.com.

Si una API está compuesta por varios servicios tiene que llamarse de una forma que facilite su detección. Una forma de hacerlo es que los Nombres de Servicio compartan un prefijo común. Por ejemplo, build.googleapis.com y buildresults.googleapis.com son servicios que forman parte de la API de Google Build.

Nombres de paquetes

Los nombres de paquetes declarados en los archivos .proto de la API tienen que ser coherentes con los Nombres de Productos y Servicios. Los nombres de paquetes para las API que tienen una versión deben terminar con la versión. Por ejemplo:

// Google Calendar API
package google.calendar.v3;

Una API abstracta que no está asociada con un servicio de forma directa, como la API de Google Watcher, tiene que usar nombres de paquetes proto coherentes con el nombre del Producto:

// Google Watcher API
package google.watcher.v1;

Los nombres de los paquetes de Java que se especifican en los archivos .proto de la API deben coincidir con los nombres del paquete proto con prefijo del nombre del paquete de Java estándar (com., edu., net., etcétera). Por ejemplo:

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

ID de colección

Los ID de colección tienen que usar la forma plural y lowerCamelCase, además de la ortografía y la semántica del inglés estadounidense. Por ejemplo: events, children, o deletedEvents.

Nombres de interfaces

Para evitar la confusión con los Nombres de Servicios como pubsub.googleapis.com, el término interface name hace referencia al nombre usado cuando se define un service en un archivo .proto:

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

Puedes considerar a service name como una referencia a la implementación real de un conjunto de API, mientras que interface name se refiere a la definición abstracta de una API.

Un nombre de interfaz tiene que usar un sustantivo intuitivo como Calendar o Blob. El nombre no tiene que entrar en conflicto con ningún concepto establecido en lenguajes de programación y sus bibliotecas del entorno de ejecución (por ejemplo, Archivo).

En el caso poco frecuente de que interface name entre en conflicto con otro nombre dentro de la API, se debe usar un sufijo (por ejemplo, Api o Service) para eliminar la ambigüedad.

Nombres de métodos

Un servicio podría, en su especificación de IDL, definir uno o más métodos de RPC correspondientes a los métodos en las colecciones y recursos. Los nombres de los métodos tienen que seguir la convención de nomenclatura de VerbNoun con capitalización medial mayúscula, en la que el sustantivo, por lo general, es el tipo de recurso.

Verbo Sustantivo Nombre del método Mensaje de la solicitud Mensaje de la respuesta
List Book ListBooks ListBooksRequest ListBooksResponse
Get Book GetBook GetBookRequest Book
Create Book CreateBook CreateBookRequest Book
Update Book UpdateBook UpdateBookRequest Book
Rename Book RenameBook RenameBookRequest RenameBookResponse
Delete Book DeleteBook DeleteBookRequest google.protobuf.Empty

La parte del verbo del nombre del método tiene que usar el modo imperativo, que se usa para dar órdenes o directrices, en lugar del modo indicativo, que se usa con el fin de hacer preguntas.

Esto se confunde con facilidad cuando el verbo está en una pregunta sobre un subrecurso en la API que, con frecuencia, se expresa en el modo indicativo. Por ejemplo, indicar a la API que cree un libro es CreateBook con certeza (en el modo imperativo), pero para consultar a la API sobre el estado del publicador del libro, se debería usar el modo indicativo, como IsBookPublisherApproved o NeedsPublisherApproval. Para continuar con el uso del modo imperativo en situaciones como esta, confía en los comandos como “check” (CheckBookPublisherApproved) y “validate” (ValidateBookPublisher).

Los nombres de los métodos no deben incluir preposiciones (p. ej., “For”, “With”, “At”, “To”). Por lo general, los nombres de métodos con preposiciones indican que un método nuevo está en uso en el lugar donde un campo se debería agregar a un método existente o que el método debería usar un verbo distinto.

Por ejemplo, si ya existe un mensaje CreateBook y piensas agregar CreateBookFromDictation, considera un método TranscribeBook en su lugar.

Nombres de mensajes

Los nombres de los mensajes deben ser cortos y concisos. Evita usar palabras redundantes o innecesarias. Los adjetivos se pueden omitir si no hay ningún mensaje correspondiente sin el adjetivo. Por ejemplo, Shared en SharedProxySettings no es necesario si no hay ninguna configuración de proxy no compartida.

Los nombres de los mensajes no deben incluir preposiciones (p. ej., “With”, “For”). En general, los nombres de mensajes con preposiciones se representan mejor con campos opcionales en el mensaje.

Mensajes de solicitud y respuesta

Los mensajes de solicitud y respuesta para los métodos de RPC deben llamarse como los nombres de los métodos con el sufijo Request y Response, respectivamente, a menos que la solicitud del método o el tipo de respuesta sea una de las opciones siguientes:

  • un mensaje vacío (usa google.protobuf.Empty)
  • un tipo de recurso o
  • un recurso que representa una operación

Esto se aplica, por lo general, a las solicitudes o respuestas usadas en los métodos estándar Get, Create, Update o Delete.

Nombres de enumeraciones

Los tipos de enumeración deben usar nombres con CapitalizaciónMedialMayúscula.

Los valores de enumeración deben usar NOMBRES_EN_MAYÚSCULAS_CON_GUIONES_BAJOS. Cada valor de enumeración debe finalizar con un punto y coma, no con una coma. El primer valor se tiene que llamar ENUM_TYPE_UNSPECIFIED como se muestra cuando un valor de enumeración no se especifica de forma explícita.

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

Wrappers

Los mensajes que encapsulan los tipos de enumeración proto2 en los que el valor 0 tiene otro significado que no sea UNSPECIFIED se lo tiene que llamar con el sufijo Value y tener un campo único llamado value.

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

Nombres de campos

Las definiciones de campo en los archivos .proto deben usar nombres_en_minúscula_separados_por_guiones_bajos. Estos nombres se asignarán a la convención de nomenclatura nativa en el código generado para cada lenguaje de programación.

Los nombres de los campos no deben incluir preposiciones (p. ej., “for”, “during”, “at”), como en los ejemplos siguientes:

  • reason_for_error debería ser error_reason
  • cpu_usage_at_time_of_failure debería ser failure_time_cpu_usage

Los nombres de campos no deben usar adjetivos pospositivos (modificadores ubicados después del sustantivo), por ejemplo:

  • items_collected debería ser collected_items
  • objects_imported debería ser imported_objects

Nombres de campos repetidos

Los campos repetidos en las API deben usar formas plurales adecuadas. Esto coincide con la convención de las API de Google existentes y la expectativa común de los desarrolladores externos.

Tiempo y duración

Para representar un punto en el tiempo independiente de cualquier zona horaria o calendario, se debe usar google.protobuf.Timestamp y el nombre del campo debe finalizar con time, como start_time y end_time.

Si el tiempo se refiere a una actividad, el nombre del campo debe tener formato verb_time, como create_time, update_time. Evita usar el verbo en tiempo pasado, como created_time o last_updated_time.

Para representar un lapso entre dos puntos en el tiempo independiente de cualquier calendario y concepto como “día” o “mes”, se debe usar google.protobuf.Duration.

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

Si tienes que representar campos relacionados con el tiempo con un tipo de número entero por cuestiones de compatibilidad o herencia, incluidos el tiempo de reloj, la duración, el retraso y la latencia, los nombres de los campos deben tener el formato siguiente:

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}
message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

Si tienes que representar la marca de tiempo con el tipo de string por cuestiones de compatibilidad o herencia, los nombres de los campos no deben incluir ningún sufijo de unidad. La representación de string debe usar el formato RFC 3339, p. ej., “2014-07-30T10:43:17Z”.

Fecha y hora del día

Para las fechas que son independientes de la zona horaria y la hora del día, se debe usar google.type.Date y tiene que tener el sufijo _date. Si se debe representar una fecha como una string, debe ser en el formato de fecha ISO 8601 AAAA-MM-DD, p. ej., 2014-07-30.

Para las horas del día que son independientes de la zona horaria y la fecha, se debe usar google.type.TimeOfDay y tiene que tener el sufijo _time. Si se debe representar una hora del día como una string, debe ser en el formato de 24 horas ISO 8601 HH:MM:SS[.FFF], p. ej., 14:55:01.672.

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

Cantidades

Las cantidades representadas por un tipo de número entero deben incluir la unidad de medida.

xxx_{bytes|width_pixels|meters}

Si la cantidad es un número de artículos, entonces el campo tiene que tener el sufijo _count, por ejemplo, node_count.

Campo de filtro de listas

Si una API admite el filtrado de recursos mostrados por el método List, el campo que contiene la expresión de filtro tiene que llamarse filter. Por ejemplo:

message ListBooksRequest {
  // The parent resource name.
  string parent = 1;

  // The filter expression.
  string filter = 2;
}

Respuesta de la lista

El nombre del campo en el mensaje de respuesta del método List, que contiene la lista de recursos, debe ser una forma plural del nombre del recurso en sí. Por ejemplo, un método CalendarApi.ListEvents() debe definir un mensaje de respuesta ListEventsResponse con un campo repetido llamado events para la lista de recursos mostrados.

service CalendarApi {
  rpc ListEvents(ListEventsRequest) returns (ListEventsResponse) {
    option (google.api.http) = {
      get: "/v3/{parent=calendars/*}/events";
    };
  }
}

message ListEventsRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

message ListEventsResponse {
  repeated Event events = 1;
  string next_page_token = 2;
}

Capitalización medial

Salvo los nombres de campos y los valores de enumeración, todas las definiciones dentro de los archivos .proto deben usar nombres con CapitalizaciónMedialMayúscula, como lo define el Estilo de Java para Google.

Abreviatura de nombre

Para las abreviaturas de nombres conocidos entre los desarrolladores de software, como config y spec, se tienen que usar las abreviaturas en las definiciones de las API, en lugar del nombre completo. Esto hará que el código fuente sea fácil de leer y escribir. En las documentaciones formales, se tiene que usar el nombre completo. Ejemplos:

  • config (configuración)
  • id (identificador)
  • spec (especificación)
  • stats (estadísticas)
¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…