Internal API - Some larger generic methods, or many very specific methods

Question

I'm building a web API that is going to be consumed by several internal systems. Naturally the different systems have different requirements. The consumers may create change requests to the API, when they need new features. Everything is within my organization. How do I know when a change request is too specific and when it should be implemented?

The API is supposed to be a common API and not consumer specific, but it will be consumed by different systems. So let's say that I have the following simple model (I cannot share my actual model):

public class Customer
{
    public int Id;
    public Order[] Orders;
}

public class Order
{
    public int Id;
    public DateTime Date;
    public Product[] Products;
}

public class Product
{
    public int Id;
    public ProductType ProductType;
}

public enum ProductType
{
    DVD,
    Book,
    CD
}

One consumer will want to fetch all orders for a specific customer. So I'll write a specific method for that:

www.myapi/orders/getByCustomer/1

That's a pretty common thing to do. Next consumer wants to fetch all orders for a specific customer but only where the ProductType is DVD. It would look something like this:

www.myapi/orders/getByCustomerAndProductType/1/DVD

But wait, this can be achieved by first using getByCustomer, and then let the consumer manually filter on ProductType on their end. So the feature is already available, but the consumer will get more data than it actually needed. Should I accept the new feature, or should I ask the consumer to use the getByCustomer method and filter the data on their end. How do I decide what responsibilities the client should have, and when the logic should be implemented in the API? Are there any general guidelines?

I'm thinking of providing the API as OData as well, but then the client will be responsible for querying which they don't like.

Answer 1

That may or may not be "pretty common", but there are better solutions to the problem. Use query parameters instead.

GET /www.myapi/orders?customerId=1
GET /www.myapi/orders?customerId=1&productType=DVD

One flexible endpoint will let you tailor your response content to the needs of different customers.

In general, some thought should go into whether client needs are different enough to provide different APIs entirely, or whether the needs of all clients can be met with a single API.

Answer 2

Well, since it's an internal API the company has actually control over all parameters and constraints. The involved teams and their managers can now decide, taking into account:

• Is bandwidth important? If yes, make the producer implement more filtering, i.e. implement the requested change.
• Is latency important and bandwidth is not very limiting? Then you can afford to send more data and the clients have more flexibility to filter out their desired data (which might change more frequently than you'd like to change your service).
• Which team has more resources at the moment? Let them do the work on their side.
• As a general principle, try to offer services that are based on business capabilities. Why do the clients need that data? If they just want to display it somewhere, ok. But otherwise maybe it makes more sense to offer the business capability as the service API and not the data behind it (see this article which talks about SOA but has broader relevance to any kind of services)