sa Nagsalita ko ang Google para sa unpolletedly sinabi "no" sa mga pag-iisip ng modernidad. Ang Google Calendar's Secret Engineer Weapon: Restraint Salamat sa pag-aralan ang Fullstack Engineer! Subscribe for free to receive new posts and support my work. Subscribe sa "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. Ang kanilang commitment sa simplicity ay tumutulong sa GCal upang matatagpuan ang kanyang posisyon bilang ang default calendar para sa bilyong regular na mga tao. Ngunit para sa mga kliyente ng API, ang parehong simplicity ay gumagawa ng buhay ng tragically mabigat. Paano ang kompleksidad na ito ay tumuturo sa, at kung ano ang dapat natutunan natin mula dito bilang mga manunulat. Ang Problema: Magkaroon ng Data In-Sync Ikaw ay lumikha ng isang cool na bagong kalendaryo na tinatawag na Cool Calendar. Upang makatulong sa mga gumagamit na magsimula, i-import ang mga ito ng mga kasalukuyang Google Calendar. Ito ay nangangailangan ng access sa data ng Google Calendar ng iyong mga gumagamit. Tingnan mo ang GCal API at makita ang mga tipikal na suspek: “Cool,” sa tingin mo. “I just gotta get the , pagkatapos ay makakuha ng lahat ng mga kaganapan para sa kalendaryo na ito. Kapag kailangan kong i-update ng isang kaganapan, ginagamit ko ang mula sa get ang reaksyon.” calendarId eventId events Maaari mong gawin ang lahat ng ito sa pamamagitan ng ilang simpleng mga function: Ang lahat ng mga kaganapan ay sa iyong DB, at sila ay nagpapakita din sa GCal ng user pagkatapos ng isang user update ng isang kaganapan mula sa iyong UI. I-open ang GCal app, lumikha ng isang bagong event na tinatawag na "Celebrate at Denny's," at nakikita ang iyong cinnamon roll pancakes. Cool Cal app ay binubuo, ngunit ang bagong event ay hindi nagpapakita. Ang iyong empty stomach sink as you realize you only implemented half the solution (CoolCal → GCal). Kailangan mo pa rin upang matugunan na ang mga pagbabago sa GCal ay mag-propagate sa Cool Calendar (GCal → CoolCal). ang negosyo Alam mo na ang iba ay nakikipag-ugnayan sa mga kaso ng paggamit na ito bago, kaya i-revisit ang GCal API docs. Salamat, nakikita mo ang isang guide na tinatawag “ » » I-synchronize ang mga resource Ang guide ay short, na nag-aalok sa iyo ng kaligtasan. Sa tingin mo, kailangan mo lamang ng isang paaralan ng mga telepono. Dahil hindi mo alam kung ano ang maraming mga events ay na-update o kapag ang mga ito ay, alam mo na kailangan mo ng isang loop upang makuha ang lahat ng mga ito. Makakakuha ng sensasyon. Salamat, ang mga docs ay naglalaman ng isang buong bahagi ng ito sa Java. Siya ay gumagamit ng mga ang looping strategy, na nagbibigay sa iyo ng feeling smart. do-while Siguro maaari mong i-convert ito sa JavaScript at pumunta. anger Ito ay isang oras, at i-convert ang snippet sa isang function ng JavaScript na tinatawag na I-update ang iyong API. syncGcal() Ito ay gumagana! Kapag bumalik na ako , ang mga bagong data ng GCal ng isang user ay idinagdag sa CoolCal. syncGcal() Ikaw ay nagsisimula upang ilagay ang New York Style Cheesecake para sa iyong mga problema. Kapag bumalik na ako sa UP, i'll start building a new me. Ang syncToken ay hindi patuloy sa anumang lugar syncGcal() ay gumagana lamang kapag itinatag ito manually How often should I run syncGcal() ? Lahat ng oras? Lahat ng minuto? Where will I store the token? Lokasyon ng Deposit? ang Ang mga koleksyon? user Isang bagong koleksyon? What happens if the token becomes invalid? Mayroon ba akong retreat? Kailangan ko bang gawin ang isang buong impormasyon bilang backup? Ano ang limitasyon ng quota? Ano ang gagawin ng isang user sa panahon ng pagbabago? Ipinanganak mo ang iyong pag-asa - sa guideline para sa hindi i-warn sa iyo tungkol sa mga kaso ng edge, pagkatapos sa iyong naivety para sa pag-uusapan ito ay dapat. ang negosyo "Hindi ko lamang - alam ko ang tulong," sinasabi mo sa iyong sarili, tulad ng iyong nagtatrabaho sa therapy. Ikaw ay sigurado na ang mga API docs ay may isang paraan na tinatawag na na ikaw ay nangangahulugan. syncResources() O ito ay ibinibigay bilang isang serbisyo? tulad ng ilang kumpanya ng YC na mag-sync ang lahat ng iyong data para sa iyo. Gayunpaman, magkaroon ng isang disciple ng Richard Stallman na may isang MIT repo na maaari mong ipakita sa Claude. > clone the two-way sync stuff from github.com/stallman-cal. no bugs. ang depression Ang mga official docs ay puwede. Lahat ng mga kumpanya ng YC ay mga building agents. Stallman ay hindi naniniwala ang iyong kalendaryo app para sa profit. (Ito ay isang proyekto na tinatawag na Ang mga ito ay may 200 na mga star, ngunit hindi dapat na itinuturing.) Mga Calendar ng Compass Walang interesado sa iyong bidirectional sync feature. Sa katunayan, ikaw ay lahat lamang. Ang isang single tear ay bumaba sa iyong mekanikal na keyboard bilang makikita mo na hindi mo pumunta sa Denny's ngayon. Mga Acceptance Pagkatapos ng home-made French toast at isang postprandial walk, ikaw ay makipag-usap sa iyong destiny na magtatrabaho tulad ng isang tunay na engineer at gawin ito sa iyong sarili. Sa loob ng isang taon na ang nakalipas, ito ay finally ginawa. Ngunit hindi mo nawala ang pag-iisip “Bakit ang GCal ay ginawa ito sa paraan na ito?” Kailangan ba ito na maging complicated?” Mga Requirements I-set ang iyong sarili sa mga sapatos ng Google sa pamamagitan ng reverse-engineering ang mga kinakailangan sa pamamagitan ng isang (Ang mga ito ay Mga Produkto ng Doc ang solusyon Ito ay masaya, kaya mag-documentate ang solusyon upang matugunan ang mga kinakailangan bilang isang sa pamamagitan ng TDD. Mga teknikal na disenyo Doc Mga Analysis Sa katapusan, ikaw ay may kakayahang sabihin kung ang GCal's "Give 'em a token" solusyon ay isang mahusay na. Mga pahinang tumuturo sa Token Pagination Maaari nila i-hide ang kompleksidad mula sa kliyente upang hindi nila kailangan upang malaman ang lahat (multi-region replication, halimbawa) Opaque tokens protect the client from overwhelm. Sa pamamagitan ng kontrolin kung saan ang tokens ay umalis, ang GCal ay maaaring matutunan na ang mga kliyente ay makakita ng mga deletions sa panahon ng incremental sync. Timestamp-based approaches ay hindi maaaring gumawa ng garantiya na ito. Cleanly handles deletions. Ang Google ay maaaring mababago ang kanyang storage backend, sharding strategy, o topology nang walang epekto sa mga kliyente. Ito ay sigurado na ginawa ang migration mula sa NoSQL (Megastore) sa NewSQL (Spanner) mas madaling sa 2010s ( ang mga ito) Easier implementation changes. Mga pahinang tumuturo sa highscalability.com mga weaknesses Ang webhook ay nagpapakita sa iyo kung ano ang nagbabago, ngunit hindi kung ano. Iyon ay nangangahulugan na ang bawat push notification ay nagdadala ng isang bagong incremental sync call. Ito ay magiging chatty kapag ang mga gumagamit ng power ay gumagawa ng mga karaniwang mga tweaks. Bakit hindi magbigay ng isang mababang diff sa push payload mismo, o sa halos ibig sabihin na kung ano ang mga event ID ay bago? Push is disconnected from sync. . Incremental syncs ay hindi compatible sa at ang Parameters. Kailangan mo upang piliin ang isa o ang iba pang paraan. Ito ay isang bumalik para sa mga tao, na nag-iisip sa terms ng oras mas madaling kaysa sa tokens. Some filters are incompatible timeMin timeMax Ang mga token ng pahina ay ephemeral. Kung ang isang client crashes mid-pagination (pagkatapos ng pahina 3 ng 7), sila ay dapat i-restart ang buong sync. Para sa mga malaking calendars, ito ay sakit. Ang isang alternatibo ay ang durable na pahina tokens na pag-survive sa pamamagitan ng sesyon, o checkpointing ang pag-sync progression. No partial sync recovery. Alternatibo (at bakit hindi nila ginagamit) ang bottom line Ang sync token + cursor pagination approach ay isang Ito ay ang parehong pattern na ginagamit ng Microsoft Graph (delta tokens), Stripe (pagination cursors), at karamihan ng enterprise APIs. pragmatic, battle-tested pattern Pinili ng Google ito dahil ito ay nagbibigay-daan sa kanila na i-hide ang internal complexity habang nagbibigay ang "good enough" sync semantics para sa 99% ng mga kaso ng paggamit ng calendar. Ang mga alternatibo (event sourcing, CRDTs, OT) ay kailangan lamang kung ang GCal ay nangangailangan ng real-time collaboration o true offline-first P2P sync. ang full picture Kung ang target ng Google sa GCal ay upang lumikha ng mga revenue, sila ay nag-aalok ng higit pa ng mga dokumento, mga video, at webinars. Mayroon itong isang cute Developer Advocate, layered API pricing, at isang Customer Success Team. npm i gcal Ngunit ang target ng Google sa GCal ay hindi mas ambitioso: >> Don’t annoy regular users so much that they download Apple Calendar. Ito ay hindi kailangang maghintay ng maraming mula sa isang libreng API. Ito ay mahirap na maaari mong mag-integrate sa GCal sa unang lugar Ang GCal ay nagtatagumpay sa kanyang responsibilidad bilang isang pangunahing bahagi ng iyong app sa pamamagitan ng pag-priorize ang reliability kaysa sa convenience ng adoption: Walang maraming mga disappointment. Ang API ay gumagawa kung ano ang sinasabi ng mga dokumento, kahit na hindi nila sinabi ang maraming. Hindi sila nagbabago sa iyong mga pagbabago Ngayon ay, kapag nagsimula sila sa pag-iisip, "I know, I'll just integrate with GCal." there is a gap between the developer’s expectations and reality Sa kasalukuyang, ang developer ay dapat i-closing ang gap na ito sa panahon, pag-iisip, at isang pagbabago ng innocence. Ngunit ang Google ay maaaring mabawasan ang sakit sa pamamagitan ng magbigay ng higit pa ng mga resource. Halimbawa, ang mga docs ay maaaring magbigay ng higit pa ng implementation guidance. Ang mga sample ng code ay maaaring i-evolve mula sa bare repos sa mga demo application. Sa balanse, maging simple ang API ay ang katotohanan. Ang isang primitive API ay maaaring masakit ang mga gumagamit ng power. Ngunit kung ito ay hindi nakakaapekto sa UX, revenue, retention, o ang brand, pagkatapos ay mangyaring simple. Takeaways para sa mga Builder Paggawa ng isang Public Sync API Keep it boring: use existing standards Nakita namin dito kung paano ang API ng GCal ay binuo sa pagitan ng cursor at sync tokens. Ang kanyang event model ay din binuo sa paligid ng mga itinatag na mga patakaran: CalDAV, iCalendar, at RRULEs. Ito ay isang malaking dahilan kung bakit mayroong maraming kamangha-sukses na integrations ng GCal dahil ang kanilang API ay dumating sa publiko noong 2006 (agawin sa Yahoo). Use cursor pagination when the data is a moving target Kapag bumalik na ako sa UP, i'll start building a new me. Mga halimbawa: Calendars, feeds, audit logs, append-only streams. Use offset pagination when the data is stable Kung ang data ay static at hindi may concurrent writes, maaari mong pumunta sa loob ng isang mas simpleng paraan. Halimbawa: Mga resulta ng paghahanap na may mga numero ng pahina, admin table para sa maliit na data. Don’t oversell the API Alam mo kung ano ang feeling na maging excited sa araw-araw upang magsisimula ng isang PR at pagkatapos para sa isang hike ... lamang upang malaman na ito ay mas karaniwang kaysa sa tinanong mo at hindi makita ang araw-araw hanggang sa susunod na afternoon. Ang API ng Google ay hindi nag-aalok upang gawin ang lahat para sa iyo. Ang katapusan na produkto ay mag-sale ang API: mag-save ang iyong oras na mag-enjoy ang iyong mga gumagamit sa iyong produkto bago mag-alala tungkol sa pag-enjoy ang mga developer na mag-integrate sa kanya Don’t break things Kung ang iyong integration ay pangunahing sa produkto ng ibang tao, pagkatapos ay pumunta langka. Magbayad ng higit pa ng oras upang i-test ang migration. Kumuha ng feedback sa mga docs bago mag-launch nila. Magpadala ng "head up" emails at mga mensahe ng terminal upang hindi na kailangang mag-surprise. Ito ay nangangailangan ng isang pagbabago ng identity mula sa "crackhead vibe coder" na nag-break ang mga bagay sa prod sa "disciplined software engineer." Hindi mo kailanman makakakuha ng mga bagay, ngunit makakakuha ka ng responsibilidad. Ang isang breaking change ay magagawa ng higit pa ng damages kaysa sa three features ay magagawa ng good. Ang GCal's API ay stabilong, kaya ang aking sleep score, kasiyahan, ay hindi nawala mula sa paggamit nito. Kapag binubuo ng isang public sync API Don’t start with an integration "Pero ang aking mga gumagamit ay hindi gumagamit ng aking app kung hindi ito integrates sa mga tool na ginagamit nila." "Pero ang aking mga gumagamit ay hindi gumagamit ng aking app kung hindi ito integrates sa mga tool na ginagamit nila." Siguro, pero dapat mong sabihin ito sa iyo. Ang pagdaragdag ng isang integration ay isang mahal na side quest sa iyong produktong merkado-fit journey. Kung ang value prop ay mahusay na, hindi nila may problema upang bumuo ng isang bagong account at magdagdag ng data mula sa pangunahing. Accept that Pareto is right Sa iba pang mga salita, ang unang 20% ng mga gawain ay magkaroon ng 80% ng oras. Ang surface para sa edge cases at gotchas ay lumalaki kapag i-implementate. Ang mga dokumento ng Google ay hindi lamang ang mga taong mag-atubiling sa iyo sa pag-iisip na ang mga bagay ay maaaring maging simple at libre. Matatagpuan ang kanilang mga promise sa pamamagitan ng pagitan ng retries, idempotency, fallback, delta syncs, offline, token invalidation, quotas, at conditional requests (ETags). Hindi mo kailangang lahat ng mga ito para sa iyong MVP, ngunit maghintay na sila ay dumating sa katapusan. Simplicity for one party means complexity for another Mga pahinang tumuturo sa complex backend Good para sa regular na gumagamit → difficult para sa power-users Ang simpleng presyo → complex R&D Simple API → Complex Integration Ang susunod na beses na ikaw ay nag-iisip, "I'm just going to use this free API, it looks straightforward," tulungan mo: It’s either free or simple; Someone always pays. Pumunta na ang iyong pancakes.
