en Eu eloxiaba a Google por dicir sen desculpas "non" ás tentacións da modernidade. Arma de enxeñaría secreta do calendario de Google: Restraint Grazas por ler Fullstack Engineer! subscribirse gratuitamente para recibir novas publicacións e apoiar o meu traballo. Subscrición "Use a frontend framework." No. JavaScript. "Use Typescript." No. Javascript. "Use a trendy CSS tool." No. CSS classnames. "Give us a native desktop app." No. Browser. "Give us dark mode." No. "Make it really fast." No. O seu compromiso coa simplicidade axudou a GCal a defender a súa posición como o calendario predeterminado para miles de millóns de persoas ordinarias. Para os clientes da API, con todo, esa mesma simplicidade complica a vida traxicamente. Como se desenvolve esa complexidade e que podemos aprender dela como construtores. O problema: manter os datos in-sync Estás construíndo un novo calendario cool chamado Calendario Cool. Para axudar aos usuarios a comezar, permítelles importar o seu calendario de Google existente. Isto requirirá o acceso aos datos do Calendario de Google dos seus usuarios. Mire a API de GCal e ve os sospeitosos típicos: “Cool,” pensas. “Eu só teño que obter o , a continuación, obtén todos os eventos para ese calendario. Cando teño que actualizar un evento, A partir do GET unha resposta”. calendarId eventId events Podes facer todo isto con algunhas funcións simples: Todos os eventos están no teu DB, e tamén aparecen no GCal do usuario despois de que un usuario actualice un evento da túa interface. Abre a aplicación GCal, crea un novo evento chamado "Celebrate at Denny's", e agarda as súas panquecas de canela. A aplicación Cool Cal está aberta, pero o novo evento non aparece. O seu estómago baleiro afunda ao darse conta de que só implementou a metade da solución (CoolCal → GCal). Aínda hai que asegurarse de que os cambios de GCal se propaguen a Calendario fresco (GCal → CoolCal). Negación Vostede sabe que outros atoparon este caso de uso antes, polo que revisita os documentos da API de GCal. Afortunadamente, atopas unha guía chamada " » » Sincronizar recursos de forma eficaz A guía é curta, o que o fai máis cómodo. Parece que só tes que engadir algúns máis chamadas. Xa que non sabes cantos eventos foron actualizados ou cando foron, sabes que necesitarás un ciclo para recoller todos eles. Teñen sentido Afortunadamente, os documentos inclúen un fragmento completo deste en Java. Incluso se utiliza a estratexia looping, que fai que se sinta intelixente. do-while Seguro que só pode converter iso en JavaScript e seguir adiante. rabia Pasou unha hora, e converteu con éxito o fragmento a unha función de JavaScript chamada Actualiza a túa API. syncGcal() que funciona! cada vez que corras , os novos datos GCal dun usuario engádense a CoolCal. syncGcal() Vostede decide incluír o New York Style Cheesecake para os seus problemas. Mentres está no seu camiño de saída, algunhas preguntas xorden no seu cerebro canso... O sincToken non persiste en ningures syncGcal() só funciona cando se chama manualmente How often should I run syncGcal() ? Cada hora? Cada minuto? Where will I store the token? O almacenamento local? A súa Unha colección? user Unha nova colección? What happens if the token becomes invalid? ¿Podo seguir recorrendo? Necesito facer unha importación completa como copia de seguridade? E os límites das cotas? Que pasa se un usuario fai un cambio durante este proceso? Vostede se enfada - na guía por non avisalo sobre estes casos de vantaxe, entón na súa inxenuidade por asumir que debería. Negociación "Eu non estou só - podo chegar a buscar axuda", di a si mesmo, do mesmo xeito que practicou na terapia. Estás seguro de que os documentos da API terán un método chamado que ti esquecías. syncResources() Ou será ofrecido como un servizo? como algunha empresa YC que sincronizará magicamente todos os seus datos para ti. Polo menos, haberá un discípulo de Richard Stallman que ten un repo do MIT ao que pode apuntar a Claude. > clone the two-way sync stuff from github.com/stallman-cal. no bugs. Depresión Os documentos oficiais están abertos. Todas as empresas YC son axentes de construción. Stallman non confía na túa aplicación de calendario para fins lucrativos. (Hai un proxecto MIT chamado , pero só ten 200 estrelas. non se pode confiar.) Calendario Compás Ninguén se preocupa pola súa función de sincronización bidireccional. De feito, están todos sós. Unha soa lágrima cae sobre o seu teclado mecánico ao darse conta de que hoxe non vai ir a Denny's. aceptación Despois dun brinde francés caseiro e dun paseo postprandial, chegarás a un acordo co teu destino para actuar como un verdadeiro enxeñeiro e facelo ti mesmo. Unhas semanas máis tarde, por fin rematou. pero aínda non podes deixar de preguntarte “Por que o PP fíxoo deste xeito?” “Tivo que ser tan complicado?” Os requisitos Vostede ponse nos zapatos de Google ao reverter os requisitos en forma de O PRD . Requisitos do produto Doc A solución Foi divertido, polo que documenta a solución para cumprir eses requisitos como un O TDD. Deseño técnico Doc Análise Finalmente, vostede se sente cualificado para dicir se a solución de GCal "Give 'em un token" foi unha boa. Recomendacións de Token Pagination Poden ocultar a complexidade do cliente para que non teñan que entender todo (replicación multi-rexión, por exemplo) Opaque tokens protect the client from overwhelm. Ao controlar cando expiran os tokens, GCal pode asegurarse de que os clientes sempre vexan as supresións durante a sincronización incremental. Cleanly handles deletions. Google pode cambiar completamente o seu backend de almacenamento, a estratexia de sharding ou a topoloxía sen afectar aos clientes. ) da Easier implementation changes. alta calidade.com debilidades O webhook dinos que algo cambiou, pero non o que. Isto significa que cada notificación push desencadea unha nova chamada de sincronización incremental. Isto faise chatty cando os usuarios de enerxía fan axustes frecuentes. Por que non incluír un dif lixeiro na propia carga útil push, ou polo menos indicar que ID de evento cambiou? Push is disconnected from sync. As sinerxias incrementales son incompatibles coa e Parámetros. Ten que escoller un método ou outro. Este é un problema para os humanos, que pensan en termos de tempo máis facilmente que en tokens. Some filters are incompatible timeMin timeMax Os tokens da páxina son efémeros. Se un cliente cae no medio da páxina (despois da páxina 3 de 7), debe reiniciar toda a sincronización. Para os calendarios grandes, isto é doloroso. Unha alternativa sería tokens de páxina duradeiros que sobrevivan a sesións, ou comprobar o progreso da sincronización. No partial sync recovery. Alternativas (e por que non foron usadas) Baixo liña O sync token + cursor pagination é unha É o mesmo patrón usado por Microsoft Graph (tokens delta), Stripe (cursores de páxina), e a maioría das APIs empresariais. pragmatic, battle-tested pattern Google escolleuno porque lles permite ocultar a complexidade interna ao mesmo tempo que proporciona semántica de sincronización "bastante boa" para o 99% dos casos de uso do calendario. As alternativas (sourcing de eventos, CRDTs, OT) só terían sentido se GCal requiría colaboración en tempo real ou sincronización P2P real offline-first. A imaxe completa Se o obxectivo de Google con GCal fose xerar ingresos, ofrecerían máis documentos, vídeos e webinars.Habería un fermoso avogado de desenvolvedores, prezo de API nivelado e un equipo de éxito do cliente. npm i gcal Pero o obxectivo de Google con GCal é menos ambicioso: >> Don’t annoy regular users so much that they download Apple Calendar. Non é xusto esperar tanto dunha API gratuíta. É incrible que poida integrarse con GCal en primeiro lugar GCal honra a súa responsabilidade como parte fundamental da súa aplicación priorizando a fiabilidade sobre a conveniencia de adopción: Non se producen moitos fracasos. A API fai o que din os seus documentos, aínda que non digan moito. Non te sorprenden cos cambios aínda que, cando pensan por primeira vez, "Eu sei, eu só vou integrar con GCal." there is a gap between the developer’s expectations and reality Actualmente, o desenvolvedor ten que pechar esa brecha con tempo, esforzo e unha perda de inocencia. Pero Google podería reducir a dor proporcionando máis recursos. Por exemplo, os documentos poderían ofrecer máis orientación de implementación. As mostras de código poderían evolucionar de repos descoñecidos a aplicacións demo. No equilibrio, manter a API simple foi o paso correcto. Unha API primitiva pode molestar aos usuarios de enerxía. Pero se non afecta o UX, as receitas, a retención ou a marca, mantéñase sinxelo. Takeaways para construtores Cando crear unha API de sincronización pública Keep it boring: use existing standards Vimos aquí como a API de GCal está construída sobre a paginación do cursor e os tokens de sincronización.O seu modelo de eventos tamén está construído en torno a estándares establecidos: CalDAV, iCalendar e RRULEs. Este é un gran motivo por que houbo tantas integracións exitosas de GCal desde que a súa API foi pública en 2006 (a diferenza de Yahoo). Use cursor pagination when the data is a moving target Cando se escriben durante a lectura, necesitas consistencia en todas as páxinas para evitar duplicidades e liñas perdidas. Exemplos: Calendarios, feeds, rexistros de auditoría, fluxos de apéndice só. Use offset pagination when the data is stable Se os datos son estáticos e non teñen escritos simultáneos, pode saír cun enfoque máis sinxelo. Exemplo: resultados de busca con números de páxina, táboa de administración para pequenos datos. Don’t oversell the API Vostede sabe como é sentirse emocionado pola mañá para rematar un PR e despois para unha subida ... só para darse conta de que é máis complicado do que pensaba e non ver a luz do día ata a seguinte tarde. A API de Google non promete facer todo por ti. O produto final venderá a API: pasa o teu tempo encantando aos teus usuarios co teu produto antes de preocuparse por alegrar aos desenvolvedores que se integran con el. Don’t break things Se a túa integración é fundamental para o produto doutra persoa, entón vai lento. Gastar máis tempo probando a migración. Obteña feedback sobre os documentos antes de lanzalos. Envíanos correos electrónicos e mensaxes de terminal para que ninguén se sorprenda. Isto require un cambio de identidade de "codificador de vibe de crackhead" que rompe as cousas en prod a "enxeñeiro de software disciplinado". Non sempre vai ter razón, pero tomar a responsabilidade en serio. Un cambio fraccionario fará máis dano que tres funcións farán ben. A API de GCal é estable, polo que a miña puntuación de sono, afortunadamente, non caeu desde que a usei. Cando se integra unha API de sincronización pública Don’t start with an integration "Pero os meus usuarios non usarán a miña aplicación a menos que se integre coas ferramentas que xa están a usar". "Pero os meus usuarios non usarán a miña aplicación a menos que se integre coas ferramentas que xa están a usar". Quizais, pero déixovos que o digan. Engadir unha integración é unha procura lateral cara na súa viaxe de produto-mercado. Se o valor prop é o suficientemente bo, non terán problema en crear unha nova conta e engadir datos desde cero. Accept that Pareto is right Noutras palabras, o último 20% das tarefas levarán o 80% do tempo. A superficie para casos de bordo e gotchas amplíase a medida que se implementa. Os documentos de Google non son os únicos que te tentarán a pensar que as cousas poden ser sinxelas e gratuítas. Limpar as súas promesas considerando retries, idempotency, fallback, sincronización delta, offline, invalidación de token, cotas e peticións condicionais (ETags). Non precisa de todos eles para o seu MVP, pero espera que cheguen ao final. Simplicity for one party means complexity for another UI sinxelo → complexo backend Bo para usuarios regulares → difícil para usuarios de enerxía Prezo sinxelo → complexo R&D API sinxelo → integración complexa A próxima vez que penses, "Só vou usar esta API gratuíta, parece sinxelo", lembra: It’s either free or simple; Someone always pays. Agora vai coller as túas patacas.
