2 deleted 4 characters in body
source | link

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 for 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.

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 for 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.

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.

1
source | link

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

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 for 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.