A discussion of APIs and API contracts and how to manage your APIs using protocol buffers, also known as protobufs.
Join the DZone community and get the full member experience. This post provides guidelines to manage APIs using protocol buffers. Check out this blog post to learn more about Protobuf API contract management. API contracts describe the surface area of the request and response of each individual API method being offered. It is something that both API providers and API consumers can agree upon and get to work developing and delivering, and then integrating and consuming. An API contract is a shared understanding of what the capabilities of a digital interface are, allowing for applications to be programmed on top of. From the Google Protocol Buffer website: Protocol buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages. When working with protobufs, Buf’s linter is the tool to use for checking the quality of protobufs. Use Buf to automate adherence to an agreed upon, community-tried-and-tested style guide. Use this linter to check that: File names adhere to the naming convention. Files with package X must be within directory X relative to the root. Service names end in Service. Method names are PascalCase. Field names are lower_snake_case. Fields and messages have a non-empty comment for documentation. Enumerations have a proper zero-value default and enum values are properly named (with a prefix).
