APIs are an essential tool to allow partners, developers, and applications to consume, communicate\u00a0,or build on top of the various capabilities your microservices provide.<\/p>\n
Building a high quality API that can scale and perform with the business ecosystem is not easy and requires putting thought and planning into everything, from choosing an execution environment to even determining what API technology you will\u00a0use.<\/p>\n
So how did we<\/em> do it? In this blog post, I will share my experience of building the API for Activity Platform at Salesforce as a guide to writing an API for your own needs. Activity Platform is a big data event processing engine that ingests and analyzes over 100 million customer interactions every day to automatically capture data<\/a> and to generate insights<\/a>, recommendations<\/a>, and feeds.<\/a> Activity Platform provides APIs to serve these to our\u00a0clients.<\/p>\n Depending on the requirement, an execution environment could be bare metal, a virtual machine (VM), or an application container. We chose application containers, as these can run on a physical machine or in a VM, and a single operating system instance can support multiple containers, each running within its own, separate execution environment. In a nutshell, containers are lightweight, portable, fast, and easy to deploy and scale, so they are a natural fit for microservices.<\/p>\n If you decide to go with containers, like we did, container orchestration will help you automate the deployment, management, scaling, and networking of containers. There are many container orchestration tools to consider: Kubernetes, Apache Mesos, or DC\/OS (with Marathon), Amazon EKS, Google Kubernetes Engine (GKE), and\u00a0others.<\/p>\n We use Nomad clusters from Hashicorp<\/a>. It\u2019s simple, lightweight, and can orchestrate applications of any type\u200a\u2014\u200anot just containers. It integrates seamlessly with Consul and Vault for service discovery and secrets management. You can easily describe the requirements a task needs to execute such as memory, network, CPU, and more along with specifying the number of instances you need to horizontally scale your\u00a0service.<\/p>\n To build an API, we chose GraphQL<\/a>. If you haven\u2019t heard of it, it is a popular alternative to other available options like REST, SOAP, Apache Thrift, OpenAPI\/Swagger or\u00a0gRPC.<\/p>\n Why did we choose\u00a0GraphQL?<\/strong><\/p>\n We wanted to build an API that can serve various clients ranging from web to mobile app. It needed to be efficient, powerful and flexible.<\/p>\n GraphQL was the best fit for our needs for a few\u00a0reasons:<\/p>\n 1). GraphQL is database agnostic and can serve data from anywhere you want for your defined business domain. This means that underneath you can use Cassandra, Elasticsearch, or an existing API from other modules for a single\u00a0query.<\/p>\n 2). It allows clients to request exactly what they need, avoiding overfetching or underfetching. If an API returns more than what a client needs, there is a performance hit, and if it returns less, multiple network calls will slow the rendering time. GraphQL avoids both of these outcomes.<\/p>\n 3). While most APIs do versioning, GraphQL serves a versionless API, as it only returns the data that\u2019s explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking\u00a0change.<\/p>\n 4). GraphQL uses a strong type system where all the types are written in schema using the Graph SDL. It serves as the contract between the client and the server with no confusion about request\/response structure.<\/p>\n 5). GraphLQ supports introspection, so schema definition can easily be shared or downloaded using various tools like GraphiQL\u00a0, GraphQL- playground, or cli\u00a0tools.<\/p>\n We used GraphQL in our Classification Insight API. Classification Insight offers information about a user and helps meeting participants know the titles and roles of other people present at the meeting. For this API, we used Kotlin<\/a> and graphql-java<\/a>, a Java implementation of\u00a0GraphQL.<\/p>\n Step 1<\/strong>: Define your schema (e.g. schema.graphqls). Every GraphQL service defines a set of types. The most basic components of a GraphQL schema are object types, which represent a kind of object you can fetch from your service. Query type is to define the entry point<\/em> of every GraphQL\u00a0query.<\/p>\n In the schema below, I have defined a query \u201cgetClassificationInsightsByUser\u201d which can be called later by posting this payload to your running api (e.g. localhost:8080\/api)\u00a0: schema.graphqls<\/p>\n # object type to describe what you can fetch schema { Step 2<\/strong>: Implement Datafetcher<\/a> (also known as resolver) to resolve the field getClassificationInsightsByUser. A resolver is basically a function provided by the developer to resolve each field of type defined in schema and return its value from the configured resources like a database, other APIs, or from cache,\u00a0etc.<\/p>\n In this example, our Query type provides a field called getClassificationInsightsByUser which accepts the argument emailAddresses. The resolver function for this field likely accesses a database and then constructs and returns a list of ClassificationInsightByUser object.<\/p>\n \/\/ Assuming you already have your data class \/\/ Write your datafetcher class \/\/ override DataFetcher’s get function. Step 3<\/strong>: Initialize GraphQLSchema and GraphQL Object (using graphql-java<\/a>) to help execute the\u00a0query.<\/p>\n \/\/ load all your schema files as string using your own utility function \/\/ create the typeRegistry from all your schema files \/\/ runtime wiring where you wire your query type to resolver Step 4<\/strong>: Write a servlet (MyAppServlet) to handle incoming requests.<\/p>\n override fun doPost(req: HttpServletRequest, resp: \/\/send the response }<\/p>\n Step 5<\/strong>: Embed the web server (jetty<\/a> in this case) in your application.<\/p>\n \/\/ The Server \/\/ HTTP connector, use HTTPS in production \/\/ Setup handler \/\/start the jetty server to listen the request Step 6<\/strong>: Build and start your application. Use your CI\/CD tool to create, publish, and deploy your Docker images to your\u00a0cluster.<\/p>\n At Salesforce, security is our top priority. Our APIs are accessible only to registered users, and they can access only the data that they have the permissions for. You may want to explore OAuth 2.0<\/a> (JWT grant type and role based access control) and Open Policy Agent<\/a> (OPA) for your access control\u00a0needs.<\/p>\n As a best practice, your authentication middleware should be placed before GraphQL and have a single source of truth for authorization in the business logic layer, avoiding the need to check at multiple places. In addition to authentication and authorization, rate limiting, data masking, and payload scanning should also be considered while designing your\u00a0API.<\/p>\n We have demonstrated how to build a scalable, efficient, secure API. We used application containers to scale, GraphQL and embedded Jetty to make it efficient and lightweight, and prioritized the security aspects of our API. We will discuss other aspects of API development, such as security and deployment, in more detail in upcoming\u00a0posts.<\/p>\n Thanks to Alex Oscherov for keeping me honest about our systems and architecture and to Laura Lindeman<\/a> for her review and feedback on improving this blog post. Also, I\u2019d like to take the opportunity to mention it has been a wonderful learning experience working with the talented folks on the Activity Platform and Infra\u00a0teams.<\/p>\n Please reach out to me<\/a> with any questions. I would love to hear your thoughts on the topic. If you\u2019re interested in solving challenges in the framework of software components built to ingest and process large volumes of streaming data from multiple sources, we\u2019re\u00a0hiring<\/a>.<\/p>\n The Journey of Building a Scalable API<\/a> was originally published in Salesforce Engineering<\/a> on Medium, where people are continuing the conversation by highlighting and responding to this story.<\/p>\n Read More<\/a><\/p>","protected":false},"excerpt":{"rendered":"Choosing an Execution Environment<\/h3>\n
A note on container orchestration<\/h3>\n
Choosing an API Technology<\/h3>\n
GraphQL in\u00a0Action<\/h3>\n
{ getClassificationInsightsByUser(emailAddresses<\/strong>: [\u201ctest1@gmail.com\u201d, \u201ctest2@gmail.com\u201d]<\/strong>) { userId, title }\u00a0}<\/p>\n
<\/em>type ClassificationInsightByUser {
organizationId: ID!
userId: String!
emailAddress: String!
title: String!
}
# Query type to define all your queries
<\/em>type Query {
getClassificationInsightsByUser(
emailAddresses: [String!]!
): [ClassificationInsightByUser]
}<\/p>\n
query: Query
}<\/p>\n
\/\/ (e.g. ClassificationInsightByUser) defined to hold the data<\/p>\n
class ClassificationInsightByUserDataFetcher:
DataFetcher<List<ClassificationInsightByUser>?> {<\/p>\n
override fun get(env: DataFetchingEnvironment):
List<ClassificationInsightByUser>? { \/\/ get the argument passed in submitted query
val emailAddresses = env.getArgument<List<String>> (EMAIL_ADDRESSES)
\/\/ write logic to get data from other API Or,
\/\/ from your business layer calling your controller\/service
\/\/ Here, just returning the static data to keep it simple.
return EntityData.getClassificationInsightByUser(emailAddresses)
}
}<\/p>\n
String schema = getResourceFileAsString(“schema.graphqls”)<\/p>\n
val schemaParser = SchemaParser()
val typeDefinitionRegistry = TypeDefinitionRegistry()
typeDefinitionRegistry.merge(schemaParser.parse(schema))<\/p>\n
val runtimeWiring = RuntimeWiring()
.type(“Query”, builder -> builder.dataFetcher(
“getClassificationInsightsByUser”, ClassificationInsightByUserDataFetcher()
)
)
.build();
\/\/ create graphQL Schema
val schemaGenerator = SchemaGenerator();
val graphQLSchema = schemaGenerator
.makeExecutableSchema(typeDefinitionRegistry,runtimeWiring);
\/\/ create graphQL
val graphQL = GraphQL.newGraphQL(graphQLSchema).build();<\/p>\n
HttpServletResponse) {
val jsonRequest = JSONObject(payloadString)
val executionInput = ExecutionInput.newExecutionInput()
.query(jsonRequest.getString(“query”))
.build()
\/\/ execute your query using graphQL.
\/\/ It will call your resolvers to get the data
\/\/ and only return the data that was requested.
val executionResult = graphQL.execute(executionInput)<\/p>\n
resp.characterEncoding = “UTF-8”
resp.writer.println(mapper.writeValueAsString(executionResult.toSpecification()))
resp.writer.close()<\/p>\n
val server = new Server();<\/p>\n
val http = ServerConnector(server)
http.host = “localhost”
http.Port = 8080
http.idleTimeout = 30000<\/p>\n
val servletContextHandler = ServletContextHandler()
servletContextHandler.contextPath = “\/”
servletContextHandler.addServlet(ServletHolder(MyAppServlet()), “\/api”)
server.handler = servletContextHandler<\/p>\n
server.start()
server.join()<\/p>\nEnsuring Your APIs are\u00a0Secure<\/h3>\n
Conclusion<\/h3>\n
Acknowledgement<\/h3>\n