Application Programming Interface (API) Design discusses best practises for creating libraries intended for general purpose or public use.

learn more… | top users | synonyms

20
votes
2answers
2k views

Should one always know what an API is doing just by looking at the code?

Recently I have been developing my own API and with that invested interest in API design I have been keenly interested how I can improve my API design. One aspect that has come up a couple times is ...
4
votes
1answer
455 views

What is the evidence that an API has exceeded its orthogonality in the context of types?

Wikipedia defines software orthogonality as: orthogonality in a programming language means that a relatively small set of primitive constructs can be combined in a relatively small number of ways ...
1
vote
0answers
42 views

Online error reporting without network access

I have developed an application for android requiring no permissions, but the biggest downside of this is that I don't have error reporting. So, I was playing around for the past week with any ...
0
votes
2answers
420 views

Should event listeners be held in weak references?

Usually event listeners shouldn't outlive object that registered them. Does it mean that event listeners should be held by weak references by default (stored in weak collections by the object ...
3
votes
1answer
211 views

Designing javascript chart library

I started coding a chart library on top of d3js: My chart library. I read Javascript API reusability and Towards reusable charts. However, I am NOT really following the suggestions because I am not ...
2
votes
1answer
2k views

Shouldn't Android's TextView.getText() return String instead of possibly mutable CharSequence?

I've just spent hours debugging some code because I forgot (actually never considered it) that TextView.getText() returns CharSequence that may be in fact a mutable class... Shouldn't it return ...
6
votes
2answers
159 views

Guidelines for returning collections from public functions

The Problem Imagine you have a function in a public API that needs to return some kind of collection. Its type is something like foo :: a -> b where b is some kind of collection. As far as I ...
0
votes
3answers
562 views

Checking for the presence of optional properties of an object

I'm designing a class that holds several types of data. Some of the properties are optional. For example, let's say I have a class that represents a person, and one of the properties is occupation. ...
3
votes
1answer
141 views

REST object with resources

I am designing a HTTP-based REST API. Let's say I have an entity called Entity that has a bunch of properties. Some of its properties are files. Let's say Entity has following properties: name: ...
2
votes
4answers
316 views

Best and safest API for a function which fills a buffer with variable-length data

I have a function which receives a buffer and returns some data in the buffer. The data can be smaller than the buffer capacity. Which is the best and safest API for this? int fn(void *buffer, ...
0
votes
1answer
161 views

Performance of One API vs Multiple API's

I was having a conversation with a colleague and although my opinion makes sense to me, I wasn't able to back it up. I'm in the process of creating an API that will be hit hundreds of thousands of ...
5
votes
4answers
512 views

Should an API be aware of client versions?

Should an API be aware of a client version? The idea of that really goes against the grain for me, but it seems like it is being pushed for in my current project. Am I wrong? Can I get some reasons ...
38
votes
5answers
11k views

How do searches fit into a RESTful interface?

When designing a RESTful interface, the semantics of the request types are deemed vital to the design. GET - List collection or retrieve element PUT - Replace collection or element POST - Create ...
1
vote
2answers
338 views

Should I use HTTP search

I am working on a web api and I am curios about the HTTP SEARCH verb and how you should use it. My first approach was, well you could use it surely for a search. But asp.net WebApi doesn't support ...
1
vote
1answer
241 views

Protecting API Keys

Iv'e moved this from SO as it's more of a design question than a code one. In many applications third party websites/programs can access the website via a key. For example, a web application hosts ...
7
votes
2answers
3k views

What is the best pattern for adding an existing item to a collection in REST API?

I'm designing a pragmatic REST API and I'm a little stuck on how best to add existing entities to a collection. My domain model includes a Project that has a collection of Sites. This is a strict ...
1
vote
2answers
225 views

Accepting a numerical range in a function call

I have encountered two ways of doing it: void foo(int from, int to); /* 'from' inclusive, 'to' exclusive */ void foo(int startIndex, int rangelength); Has one style historically been preferred ...
1
vote
2answers
3k views

How to avoid unauthorized use of an API?

I have to design a "widget", a script that partners will embed in their websites to display some UI and make calls to our API. Basically it will display our data on these sites based on some IDs they ...
5
votes
2answers
2k views

Coarse-grained views on server vs fine-grained views assembled on client vs fine-grained views with batching

I've currently got a browser talking via an "API" to the server. API is scare quoted because the API really wouldn't support another user interface very well, because it consists of every call our UI ...
2
votes
4answers
456 views

What are some good ways to represent relationship among three numbers

I'm trying to find a clean, intuitive way to implement this problem. Basically, I have three numbers, and based on relationship (less than, greater than, and equal to) among these numbers would change ...
0
votes
1answer
305 views

REST and RPC in multi-tier API

My team is developing a multi-tier API with scalability and modularity in mind. The public access point of the API is fully REST. However, we are splitting the data access layer as another tier in our ...
2
votes
1answer
279 views

How far to go when standardizing code [duplicate]

My small team and I have created a decent sized web application (~50k lines), with a fully featured API, all in Perl. As us perl hackers know.. it is easy to get sloppy. We had to port over a lot of ...
1
vote
3answers
576 views

C API in C++ with RAII, two alternatives to implement error handling (Exceptions)

I have an API written in C, which produces a result by returning a pointer to allocated memory. For using it with C++ (C++11) I've wrapped the function calls in objects, which keep the result in a ...
1
vote
1answer
78 views

Web Routing Standards

We are putting together an API to provide our vendors some simplistic direct access. I've built APIs before, and have always routed them as such: {controller}/{action}/{id} My boss, however doesn't ...
1
vote
1answer
217 views

How to create Public API wrapper with different configuration parameters

I'm looking to see if there is a design pattern that can solve the following problem. The example is fairly specific but the goal is a public + internal API. I need specific information for my ...
1
vote
2answers
116 views

Is there a way to efficiently allow a user to upload multiple content at once for e-commerce type sites?

Sellers on large sites like Amazon and Newegg need to provide names, descriptions, and images for their products to be displayed on the e-commerce sites. These sellers could have 10000+ products to ...
3
votes
3answers
395 views

What are the advantages of dynamically binding a method to class instance? [closed]

I came across Instagram's API client written in Python. In their class InstagramAPI, they bind the methods to a function in bind.py. When called, the function returns an instance of the class ...
-1
votes
1answer
2k views

A good design pattern for a Web API where models/enities are searchable by foreign keys [closed]

I was hoping someone might have some ideas on how to create a RESTful web API where models/entities are searchable by a foreign key. I see a a lot of tutorials where the functionality consist of ...
2
votes
1answer
2k views

Return values for CRUD methods?

I'm writing a basic web API in Java that does what almost all others do: take input, validate it, then do CRUD operations on the DB. I've written several APIs before, and I've pretty much already ...
0
votes
4answers
466 views

API design with references to root object

[Normally I post on StackOverflow but as this is more a design/theory question rather than a code question I'll give it a shot here] Most of my applications currently use a core object model that I ...
4
votes
2answers
962 views

Which is better API: table.add_row() or table.rows.add()?

I'm writing a library to create and manipulate Word .docx files in Python. In general, I take a lot of influence from the Microsoft VBA/C# API for Word in designing the API, figuring they've given it ...
1
vote
3answers
711 views

Is it OK to use email as an identifier in a RESTful URI?

I'm working with a team building a RESTful web service, and our current implementation utilizes the user's email as a unique identifier for the user resource, yielding URIs like the following: ...
15
votes
4answers
3k views

Why doesn't Java String have static string manipulation methods?

Why didn't Java designers create static versions of string manipulation methods in the java.lang.String class? The following methods are what I refer to, but the question can be extended to other ...
3
votes
3answers
191 views

How do I recreate this Access Control/Group/ whatever methodology in OO/MVC

I am looking at trying to rewrite an application that is mostly procedural to an MVC/OO approach in order to teach myself a deeper understanding of both. BUT, I am having some conceptual issues with ...
2
votes
1answer
177 views

Design Application to “Actively” Invite Users (pretend they have privileges)

I am designing an application where users message one another privately, and may send messages to any Entity in the database (an Entity may not have a user account yet, it is a professional database). ...
1
vote
2answers
102 views

API for expanation of complicated calculation or business rules?

In online shops there are areas with complicated rules. For example is a product visible in the product catalog is a product sold out what is the price for the product (Discounts, Promotions, ...) ...
42
votes
6answers
5k views

How necessary is it to follow defensive programming practices for code that will never be made publicly available?

I'm writing a Java implementation of a card game, so I created a special type of Collection I'm calling a Zone. All modification methods of Java's Collection are unsupported, but there's a method in ...
5
votes
2answers
1k views

Shoud I directly return a string message or rather a i18n key when dealing with JSON api?

Suppose a rest api returning this json: { "status" : "fail", "data" : { "title" : "A title is required" } } Since the client application would always adapt the error message, would it be ...
5
votes
1answer
379 views

Multiple APIs, or one API with a “chooser” parameter?

Say you have a web service, which adds business logic on top of a data source. What each API of this service pretty much looks like is - given a set of constraints, give me the items from the data ...
12
votes
2answers
5k views

Should I make up my own HTTP status codes? (a la Twitter 420: Enhance Your Calm)

I'm currently implementing an HTTP API, my first ever. I've been spending a lot of time looking at the Wikipedia page for HTTP status codes, because I'm determined to implement the right codes for ...
5
votes
2answers
518 views

What layer to introduce human readable error messages?

One of the things that I have never been happy with on any project I have worked on over the years and have really not been able to resolve myself is exactly at what tier in an application should ...
5
votes
2answers
2k views

How to handle fine grained field-based ACL permissions in a RESTful service?

I've been trying to design a RESTful API and have had most of my questions answered, but there is one aspect of permissions that I'm struggling with. Different roles may have different permissions ...
5
votes
2answers
303 views

Web Services and code lists

Our team heavily discuss the issues how to handle code list in a web service definition. The design goal is to describe a provider API to query a system using various values. Some of them are catalogs ...
0
votes
1answer
376 views

Naming a predicate: “precondition” or “precondition_is_met”? [closed]

In my web app framework, each page can have a precondition that needs to be satisfied before it can be displayed to the user. For example, if user 1 and user 2 are playing a back-and-forth ...
8
votes
2answers
780 views

Is implementing an interface defined in a subpackage an anti-pattern?

Let's say I have the following: package me.my.pkg; public interface Something { /* ... couple of methods go here ... */ } and: package me.my; import me.my.pkg.Something; public class SomeClass ...
3
votes
1answer
770 views

Using Dynamic LINQ to get a filter for my Web API

We are considering using the Dynamic.CS linq-sample included in the "Samples" directory of visual studio 2008 for our WebAPI project to allow clients to query our data. The interface would be ...
3
votes
1answer
608 views

Merge two different API calls into One

I have two different apps in my django project. One is "comment" and an other one is "files". A comment might save some file attached to it. The current way of creating a comment with attachments is ...
3
votes
1answer
561 views

API Caching Layer

Primer: We have a mobile app being served by an API (written in PHP). The main point of the app is to display products from a large items table in the database, in a multitude of different ...
2
votes
1answer
146 views

What are the guidelines for either throwing an exception or failing silently for nonvalid arguments? [duplicate]

If you look at XContainer.Add(object content) method you can see that id does not require content to be not null. It just does nothing in case of null. However List.AddRange(IEnumerable collection) ...
2
votes
3answers
1k views

Chain-of-Command/Responsibility pattern for my simple API. A good idea?

I need to write a simple API for a project I'm working on. This API will be used internally to perform some server side actions that were triggered by AJAX calls. To make things easier for me, I ...