Beta API live on testnet

The Lens Protocol leverages the power of Web3 to facilitate building more fair, transparent, and composable social applications. But building and integrating with Web3 technologies often requires a deep knowledge of smart contract development, which introduces friction for those with little Web3 development experience or for those who just want to start building. That’s why Lens Protocol will have its own API, making it easy to engage in complex development! The Lens API will leave the heavy lifting to the backend so developers can focus exclusively on crafting innovative experiences for the end-user.

The Lens API will empower you, the builder, to wield the full power that the protocol offers, bundled in an easy-to-understand GraphQL API. Read the full documentation here.

Note: This is the beta release of the API and it’s not production complete yet, which means that the schemas and endpoints are subject to change.

Here’s a high-level explanation of why the custom Lens API was created and how it can help you build faster and better 👇👇👇

🤔 Why create a custom indexer?

There are many reasons why the team went down the path of a custom indexer instead of relying on TheGraph, notably, speed, extendibility, and reliability.

1. 🏃 Speed is critical. The subgraph takes a while to broadcast the indexed event. When building a social protocol, you need the data to be available the second it has been mined in the block. Having this big dependency and not being able to control it would negatively impact the whole network effect of the API dramatically. The Lens API solves this.
2. ⏱ Quick to fix. It's crucial to be able to fix things quickly in case of an unexpected event. With an in-house indexer, bugs can be corrected and the API can be fine-tuned fast without third-party dependency.
3. 💽 Relational data structuring. With social data and unlimited pointers, the data becomes highly relational, very quickly. This means the data needs to be structured in a relational manner to allow it to be fast and scale well. Having Postgres as the database allows the protocol to do this efficiently and successfully.
4. 🔐 Content security. With the dynamic nature of the protocol accepting a contentURI of any link, not having a backend to migrate that data into safe storage for quick lookups would greatly slow down the speed of the API while also exposing users to major security issues. Lens API mitigates this by reading the contentURI as it comes in through our indexer, validating that the metadata conforms to the metadata standard, and then takes a snapshot of the metadata and moves it to our s3 safe storage. This means that when it is read back to you in the API, it’s in a place that is fast to fetch, reliable, and extracted straight in the API response for you.

With the Lens API, developers will have all the tools needed to build a social platform, but in a decentralized manner – which makes it even better, if we do say so ourselves. 💅

🏗 How does the Lens API help me, the buidlooor?

Now the part where you roll up your sleeves and see how you can use it – aka the fun part!

The API provides you with all the key information needed for building on Lens with a GraphQL, easy-to-understand schema to work with. Want to get a full profile? No worries: call profile endpoint. Want to grab all publications for a profile? No worries: call publication endpoint. Want to grab all the followers that the profile has? No worries... the list goes on. 📃

Alongside the amazing schema which allows you to grab all this data in real-time, the generated typed data has also been abstracted for you when performing write actions to the chain.

Typed data is the new(ish) way to try to show the users what they are signing. You can read more about it here: https://eips.ethereum.org/EIPS/eip-712.

Constructing all the data parameters it needs is normally quite hard and can get out of date fast with the speed at which transactions occur. On the typed data, you need to get the nonce, deadline, contract version, contract address, chain id, and the name of the contract for the signature to be signed and verified. In addition to that, you also need the information for the method typed data you like to perform. For example, if you wanted to unfollow someone using the typed data approach, you first need to find the profile follower NFT address and the tokenId you want to burn. This is not a straightforward thing to look up, but with the typed data endpoints exposed to you all you do is call:

createUnfollowTypedData(request:{profile: "0x1d"}) 

The server will construct the typed data for you! All you need to do is sign it using ethers and send it:

export const unfollow = async () => {
  // hard coded to make the code example clear
  const unfollowRequest = {
     profile: "0x1d",
  };
  
  const result = await createUnfollowTypedData(unfollowRequest);
  const typedData = result.data.createUnfollowTypedData.typedData;
  
  const signature = await signedTypeData(typedData.domain, typedData.types, typedData.value);
  const { v, r, s } = splitSignature(signature);
  
  // load up the follower nft contract
  const followNftContract = new ethers.Contract(
    typedData.domain.verifyingContract,
    LENS_FOLLOW_NFT_ABI,
    getSigner()
  );
  
  const sig = {
      v,
      r,
      s,
      deadline: typedData.value.deadline,
   },
  
  const tx = await followNftContract.burnWithSig(typedData.value.tokenId, sig);
  console.log(tx.hash);
  // 0x64464dc0de5aac614a82dfd946fc0e17105ff6ed177b7d677ddb88ec772c52d3
  // you can look at how to know when its been indexed here: 
  //   - https://docs.lens.dev/docs/has-transaction-been-indexed
}

Another benefit is the server checks every detail before it generates the typed data. So, for example, if you tried to unfollow someone you do not follow, the server will throw you a human-readable form dev error when you try to create the typed data. This is extremely helpful for debugging and saves issues with users always sending failing transactions or a mismatch of a bad request. Clean and simple.

Another fun feature of the Lens API is that it has a cache layer that caches and invalidates data as items are updated and changed. Using the API allows you to inherit the speed for your app when using it. The indexer is fast and broadcasts data as soon as it's mined.

Wait, there’s more!

The API handles reorgs for you. It also indexes your metadata into the s3 bucket. When the metadata is read from s3 it will respond in milliseconds alongside caching heavily, so your app never has to read third-party web links, protecting your app from cross-site scripting and unauthenticated CSP whitelisting. The metadata is in the schema, already read from the source and extracted to render as it would be if you were querying Twitter. The API also exposes all the NFTs on both Ethereum mainnet and polygon mainnet to allow you to fetch them easily! The API is packed with even more exciting features, which are documented in the developer docs here.

The Lens API alleviates many of the pain points devs experience when building on Ethereum. Want to build the next big social media platform on Web3? Easy! Hook up the API and start building without worrying about indexing and structuring data for efficient querying or even needing to understand solidity at all!

Data for everyone!

Some of the world’s top Data Scientists from Web2 have joined the Lens team. They are working on how algorithms can be built into Lens Protocol including things like timelines, exploring content, and any other queries that can make the experience unique and smarter.

Now, that said, this is Web3 social media, and you should decide how much of your feed is shown by algorithms or not; you should be able to choose your algorithm or even fork an existing one. It’s that choice and freedom that guides our ethos in every decision made in the building of Lens Protocol. So, you can expect the Lens API to start getting even smarter with queries soon enough. The beauty of this is if you use the API you will simply inherit these features – you don’t need to do a single thing to enjoy them!

LFGrow 🌿

Building out this API was critical for the Lens Protocol development team, empowering devs to build the next generation of social platforms! To further this mission and in collaboration with EthGlobal, join LFGrow: the online hackathon on March 18-30.

Using Lens Protocol as the foundation, LFGrow enables teams to build on the Lens Protocol by providing an abundance of hacking resources like mentors, sponsors, and software. It’s free to attend – visit https://lfgrow.ethglobal.com to apply.

Let’s grow together,

The Lens Protocol Team