Elevate Your Endpoints

If you’ve checked out our GitHub documentation, attended an office hours session, or watched a web services–related video on our YouTube channel, you may know that OData is a critical layer of the tech stack that makes up our open-source Harmony Core solution.¹ There are several reasons for this: OData is standards-based, it supports query validation (so you can choose the data available to users in a given context), and the learning curve is minimal. Developers can look at a sample OData request and immediately get a sense of what is being asked for, and our implementation of OData emits JSON, a standards-based data format that other programming languages can parse with ease.  

OData is easy to work with, but it’s important to know how to make the most of Harmony Core’s API functionality, beyond just the basics. Here are some tips for maximizing the readability and performance of the APIs that you will be generating via Harmony Core’s OData services. 

Use Meaningful Names 

Harmony Core OData services rely partially on data structures and files from Repository. That said, where appropriate, it’s a good idea to have meaningful names for data structures, as these will be turned into URLs. For example, “CustomerNumber” would be better than “CSTNBR.” 

vs.

Don’t Skimp on Data 

It might seem odd to buck a “less is more” approach to exposing your data, but in the world of Harmony Core, the better setup will likely be one in which most of your data is initially made available to developers, and the specificity of who gets what is determined when these developers create URLs, like the one below, to extract the exact information they need:  

To do this, you can configure your Harmony Core environment to enable the entity collection endpoints feature. This will generate a new GET method in each of your controller classes that exposes their respective collections (e.g., all customers, all products, etc.). You can access the GET method through an HTTP GET request without parameters.  

Plan Ahead 

The more planning you do in terms of the data you’d like to query for, the more specific you can make your endpoints. The more specific the endpoint is, the faster your query will be, as asking for a smaller amount of data takes less time than requesting a large collection.  

If you have access to an entity’s primary key, you can adjust your environment configuration to enable single entity endpoints. This will allow you to whittle down your results with a URL that incorporates the item’s unique key, thereby reducing load time. To illustrate, our sample Harmony Core service provides testable queries for all customer data, as well as for a single customer.  

When I tracked how long it took to load each page, I noticed that the “all customers” collection took 114 milliseconds, while the single customer query took about half that time—52 milliseconds. 

vs.

If you’re able to map things out in advance and narrow your data needs further, you can specify an entity’s discrete properties. For example, rather than retrieving the entire data set for an individual customer, you can query for the customer’s phone number, name, or website. To do this, check out the instructions for enabling individual property endpoints on GitHub.   

Get Familiar with Third-Party Tools 

Our documentation references two useful API-related platforms: Postman and Swagger. Postman was created as client for testing API requests and responses and has grown to include functionality for building APIs, creating reports, and generating documentation automatically. You can find more information on Postman in Harmony Core tutorial two in Github. 

While documentation generation was a recent addition to Postman’s suite of API tools, Swagger has focused on API visualization from the very beginning. In a Harmony Core environment, you will have automatic access to Swagger-generated documentation for your endpoints, but you may have a use case for one of the other tools listed on their website. 

There are plenty of additional tips scattered  
throughout the Harmony Core tutorials on GitHub, 
so we encourage you to check them out! If you have  
questions on getting started with or furthering your use  
of web services, be sure to talk to your account executive  
or join us for a session of Harmony Core Office Hours.  
We have more best practices to share from previous  
Harmony Core implementations. 

¹ Under the hood, Entity Framework Core translates OData queries into Synergy Select class operations.