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 deben adaptarse a las convenciones del 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. Estos 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. “instance” (instancia), “info” (información) y “service” (servicio) son ejemplos de nombres que generaron problemas. Los nombres que elijas deben describir claramente el concepto de las API (por ejemplo: ¿instancia de qué?) y distinguirlo de otros conceptos relevantes (por ejemplo: ¿“alert” [alerta] se refiere a una regla, una señal o una notificación?).
• Ten cuidado con los nombres que podrían causar conflictos con las palabras clave de algunos 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 son los nombres comerciales de las API, como API del Calendario de Google. En las API, las IU, la documentación, las Condiciones del Servicio, los resúmenes de cuenta y los contratos comerciales, entre otros, se deben usar los nombres de productos de forma coherente. En el caso de las API de Google, se deben utilizar los nombres aprobados por los equipos de marketing y productos.

En la siguiente tabla se muestran ejemplos de todos los 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.

Nombres de servicios

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

Si una API consta de varios servicios, estos deben llamarse de una forma que facilite su descubrimiento. Una forma de hacerlo es que los nombres de servicios compartan un prefijo común. Por ejemplo, los servicios build.googleapis.com y buildresults.googleapis.com forman parte de la API de Google Build.

Nombres de paquetes

Los nombres de paquetes declarados en los archivos .proto de la API deben que ser coherentes con los nombres del producto y servicios. Los nombres de los paquetes deben usar nombres de componentes singulares para evitar nombres de componentes singulares y plurales mixtos. Los nombres de los paquetes no deben usar guiones bajos. Los nombres de paquetes para las API con versiones 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, debe 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 las API deben coincidir con los nombres de paquetes de proto y tener un prefijo estándar de nombres de paquetes de Java (com., edu. y net., etc.). 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

En el caso de los ID de colecciones, se deben usar la forma plural, el formato lowerCamelCase y la ortografía y la semántica del inglés estadounidense. Por ejemplo, events, children o deletedEvents.

Nombres de interfaces

Para evitar confusiones con los nombres de servicios, como pubsub.googleapis.com, el término nombre de interfaz hace referencia al nombre que se usa cuando se define un service en un archivo .proto:

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

El nombre de un servicio se puede considerar una referencia a la implementación real de un conjunto de API, mientras que el nombre de una interfaz 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 debe entrar en conflicto con ningún concepto plenamente establecido en los lenguajes de programación y sus bibliotecas del entorno de ejecución (por ejemplo, File).

En el caso excepcional en que el nombre de una interfaz entre en conflicto con otro nombre dentro de API, se debe usar un sufijo (por ejemplo, Api o Service) a fin de eliminar la ambigüedad.

Nombres de métodos

Un servicio puede, en su especificación de IDL, definir uno o más métodos de RPC correspondientes a los métodos de colecciones y recursos. Los nombres de métodos deben seguir la convención de nomenclatura VerbNoun (VerboSustantivo) con mayúsculas intermedias, en la que el sustantivo, por lo general, es el tipo de recurso.

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.

En el caso de los métodos estándar, la parte del nombre del método que corresponde al sustantivo debe estar en singular para todos los métodos, excepto List, y debe estar en plural para List. En el caso de los métodos personalizados, el sustantivo puede ser singular o plural según corresponda. Métodos por lotes debe usar el sustantivo en plural.

Esto se confunde con facilidad cuando el verbo está en una pregunta sobre un subrecurso de la API que, con frecuencia, se expresa en el modo indicativo. Por ejemplo, para solicitar a la API la creación de un libro, debes usar CreateBook (en imperativo), pero, para solicitarle información sobre el estado del editor del libro, debes usar el modo indicativo, como IsBookPublisherApproved o NeedsPublisherApproval. Puedes usar verbos como “check” (CheckBookPublisherApproved) y “validate” (ValidateBookPublisher) para mantener el modo imperativo en este tipo de situaciones.

Los nombres de los métodos no deben incluir preposiciones (p. ej., “For”, “With”, “At” o “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 planeas agregar CreateBookFromDictation, considera mejor usar un método llamado TranscribeBook.

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, la palabra Shared de SharedProxySettings no es necesaria si no existen configuraciones de proxy que no sean compartidas.

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

Mensajes de solicitudes y respuestas

Los mensajes de solicitudes y respuestas de los métodos de RPC deben llamarse como los nombres de los métodos con los sufijos Request o Response, respectivamente, a menos que la solicitud del método o el tipo de respuesta corresponda a una de estas opciones:

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

Por lo general, esto se aplica a las solicitudes o respuestas que se usan en los métodos estándar Get, Create, Update o Delete.

Nombres de enumeraciones

Los tipos de enumeraciones deben usar nombres con MayúsculasIntermedias.

Los valores de enumeraciones deben usar NOMBRES_EN_MAYÚSCULAS_CON_GUIONES_BAJOS. Cada valor de enumeración debe terminar con un punto y coma, no con una coma. El primer valor se debe llamar ENUM_TYPE_UNSPECIFIED, tal como se muestra cuando no se especifica explícitamente un valor de enumeración.

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 enumeraciones proto2 en los que el valor 0 tiene un significado distinto de UNSPECIFIED deben nombrarse con el sufijo Value y tener un solo campo 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” o “at”), como en los siguientes ejemplos:

• reason_for_error debe ser error_reason.
• cpu_usage_at_time_of_failure debe ser failure_time_cpu_usage.

Los nombres de campos no deben usar adjetivos pospuestos al sustantivo, por ejemplo:

• items_collected debe ser collected_items.
• objects_imported debe 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 momento sin indicar zona horaria ni calendario, se debe usar google.protobuf.Timestamp, y el nombre del campo debe terminar con time, como start_time y end_time.

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

Para representar un intervalo de tiempo entre dos puntos sin indicar zona horaria ni calendario, ni usar conceptos como “día” o “mes”, debes 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 siguiente formato:

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 representar fechas sin indicar zona horaria ni hora del día, debes usar google.type.Date y agregar el sufijo _date. Si se debe representar una fecha como una string, debe tener el formato de fecha ISO 8601 AAAA-MM-DD, p. ej., 2014-07-30.

Para representar horas del día sin indicar zona horaria ni fecha, debes usar google.type.TimeOfDay y agregar el sufijo _time. Si se debe representar una hora del día como una string, debe tener el formato de 24 horas de 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 debe tener el sufijo _count; por ejemplo, node_count.

Campo de filtro de listas

Si una API admite el filtrado de recursos que muestra el método List, el campo que contiene la expresión de filtro se debe llamar 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 del mensaje de respuesta del método List, que contiene la lista de recursos, debe ser el plural del nombre del recurso. 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 que se mostraron.

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 de los archivos .proto deben usar nombres con MayúsculasIntermedias, como los define la guía de estilo de Google para Java.

Abreviaturas de nombres

Para las abreviaturas de nombres conocidas entre los desarrolladores de software, como config y spec, estas se deben usar 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 la documentación formal se debe usar el nombre completo. Ejemplos:

• config (configuración)
• id (identificador)
• spec (especificación)
• stats (estadísticas)