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

learn more… | top users | synonyms

42
votes
2answers
6k views

What is an Anti-Corruption layer, and how is it used?

I'm trying to figure out what the Anti-Corruption layer really means. I know that it's a way to transition/work around legacy code or bad APIs. What I don't understand is how it works and what makes ...
37
votes
6answers
3k 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 ...
31
votes
3answers
5k views

What's so bad about the DOM?

I keep hearing people (Crockford in particular) saying the DOM is a terrible API, but not really justifying this statement. Apart from cross-browser inconsistencies, what are some reasons why the DOM ...
23
votes
10answers
4k views

RESTful API design. What should I return if there are no rows?

I'm currently coding an API for a social network with the Slim Framework. My question is: What are the best practices when there are no rows to return in the json structure? Lets say that this call ...
22
votes
4answers
1k views

When creating an api should I stick with small functions and many calls, or a few calls and large functions?

I have a rails platform that I maintain. It has a lot of different web applications built on top of it. However now a client is asking for an API so that they can keep users on their site, but take ...
21
votes
10answers
1k views

API design: concrete vs. abstract approach - best practices?

When discussing APIs between systems (on the business level) there are often two different point of views in our team: some people prefer a more - lets say - generic abstract approach, other a ...
19
votes
8answers
1k views

“Public APIs are forever: Only one chance to get it right”?

In an OS book I just read that, "Public APIs are forever: Only one chance to get it right". Is it true? Is it applicable only in APIs of Operating Systems or other APIs too? For example, will this be ...
18
votes
5answers
782 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 ...
16
votes
4answers
412 views

Database abstraction — is it being overdone?

After being exposed to numerous database abstraction layers, I'm starting to wonder what the point is of every library inventing their own different paradigm to access data. Picking up a new DAL feels ...
15
votes
4answers
1k 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 ...
14
votes
3answers
719 views

Detecting IEnumerable “State Machines”

I just read an interesting article called Getting too cute with c# yield return It made me wonder what the best way is to detect whether an IEnumerable is an actual enumerable collection, or if it's ...
13
votes
7answers
2k views

Why does the Java collections APIs not have a last method?

This is for ordered collections e.g. java.util.List. Why did the language designers not include a last method? The only reasons I can think of are: ambiguity when the collection is empty (return ...
13
votes
5answers
464 views

In API design, when to use/avoid ad hoc polymorphism?

Sue is designing a JavaScript library, Magician.js. Its linchpin is a function which pulls a Rabbit out of the argument passed. She knows its users may want to pull a rabbit out of a String, a ...
13
votes
3answers
5k views

Is there a list of common usernames to reserve in a new system?

I need to reserve usernames in my new website. These generally fall into three categories 1) usernames no-one should have (eg: admin, user, service, help, root, etc) 2) names of super famous people ...
10
votes
2answers
288 views

Is the 'Law of Demeter' applicable to public/API method signatures?

Given that changes to the API/public method signature should be minimal to prevent breaking those client codes that use these methods, I was wondering if the Law of Demeter is less applicable to ...
8
votes
2answers
419 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 ...
8
votes
1answer
321 views

Versioning APIs

Suppose that you have a large project supported by an API base. The project also ships a public API that end(ish) users can use. Sometimes you need to make changes to the API base that supports ...
8
votes
1answer
570 views

What API design for storing generic data in a more specific format?

for In the project I am working on we send messages about widgets over message queues, serializing them onto the queues as XML. The XML schema contains tags for properties that are common to all types ...
7
votes
5answers
17k views

Why does java.util.ArrayList allow to add null?

I wonder why java.util.ArrayList allows to add null. Is there any case where I would want to add null to an ArrayList? I am asking this question because in a project we had a bug where some code was ...
7
votes
3answers
298 views

Is it safe to assume that one controller will only ever use one primary model?

So, I'm designing an MVC framework. In the name of keeping everything statically typed and non-magical, I've come to quite a problem with "automatically" passing models to a controller. So, ...
7
votes
5answers
3k views

How best do you represent a bi-directional sync in a REST api?

Assuming a system where there's a Web Application with a resource, and a reference to a remote application with another similar resource, how do you represent a bi-directional sync action which ...
7
votes
1answer
360 views

How To Handle Login For An Unofficial API?

I am building a tool to access some data on a site (Fitocracy) and I would like to turn it into an unofficial partial API, as no official API exists. If you are not logged in, you cannot get access ...
6
votes
3answers
219 views

Does a mobile app need more access than the public API of a site?

I have a site with a public API, and some mobile app developers have been brought in to produce an iPhone app for the site. They insist they need to see the database schema, but as I understand it, ...
6
votes
3answers
245 views

Style bits vs. Separate bool's

My main platform (WinAPI) still heavily uses bits for control styles etc. (example). When introducing custom controls, I'm permanently wondering whether to follow that style or rather use individual ...
6
votes
2answers
2k views

Implementing the command pattern in a RESTful API

I'm in the process of designing an HTTP API, hopefully making it as RESTful as possible. There are some actions which functionality spreads over a few resources, and sometime needs to be undone. I ...
6
votes
1answer
1k views

When should I use AtomPub?

I have been conducting some research into RESTful web service design and I've reached what I think is a key decision point so I thought I'd offer it up to the community to get some advice. In keeping ...
5
votes
3answers
318 views

Should I provide synonyms in an API?

I'm designing a small library and there is a strong temptation to provide synonyms to some of the exported functions. var foldl = function(){ ... }; var reduce = foldl; //reduce is a synonym for ...
5
votes
4answers
420 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 ...
5
votes
7answers
358 views

Why do certain code elements (classes, methods etc.) in public APIs get deprecated over time?

Today our professor discussed with the class that what "class X or method X get deprecated" means? From what I understood, it means, for example, that we are not going to get that method or class in ...
5
votes
9answers
379 views

Populate fields or return object

What is better to do in this type of scenario: populate fields or return an object? The situation is like this: I'm doing calculations to find the prices (inc tax, ex tax, discounted etc) of a ...
5
votes
2answers
496 views

Is a data service API a good idea?

We currently have a monolithic Rails application that is really three separate applications that make use of the same data. In trying to figure out how to properly compartmentalize and break the ...
5
votes
3answers
290 views

How do I assess tradeoff between robustness and “lazy” code in API design?

Postel's law: Be conservative in what you do, be liberal in what you accept from others. "Lazy" code (per The Pragmatic Programmer): Be strict in what you will accept before you begin, and ...
5
votes
1answer
463 views

Application internal API

I am currently building a small python CLI (Command Line Interface) application with ambition. In the first development phase I would concentrate on making it work through the CLI interface only, but ...
5
votes
1answer
2k views

When to use nested resources in a RESTful API

I have two resources: users and links. Users can have several links associated with them. I have designed my RESTful API so that you can reach the links associated with a user at the following URI: ...
5
votes
2answers
212 views

Designing a plug-in system

I'm working on a Java project and I would like to add a plug-in system. More precisely, I would like to let the user design his own module, pack it into a jar, leave it in a "plugins/" subfolder of my ...
5
votes
1answer
527 views

Sending a collection of data to an API. Multiple small calls vs one big call

I am currently creating an API and implemented a few basic REST actions such as get, update, search etc. Another program that collects data needs to synchronize these to this API. My current thought ...
5
votes
1answer
155 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 ...
4
votes
3answers
239 views

Creating a webservice API - how much “credit” should I give the client/developer

When creating a web service API, how much should I count on the developer to act by my rules? We are really aimed on creating an API so the developers shouldn't develop client side logic too much... ...
4
votes
2answers
451 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 ...
4
votes
3answers
2k views

Is it OK to return HTML from a JSON API?

On my current project I am responsible for the implementation of a service which involves the consumption of newly created RESTful APIs, documented as solely supporting JSON. The client consistently ...
4
votes
3answers
484 views

Best Practice: Should error messages be handled by the API or by the App?

I am designing an application that interacts with a RESTful API. When returning error messages like Unable to sign up user Should the error message be generated by the app? or by the API? I am ...
4
votes
3answers
264 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 ...
4
votes
1answer
648 views

Mask oAuth API key and token for pure client-side technologies

If I were to build a Twitter or Facebook application using pure client-side technologies like HTML and javascript, how would I mask/hide my API keys? For example, for Twitter I have consumer key and ...
4
votes
2answers
186 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 ...
4
votes
2answers
77 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 ...
4
votes
2answers
277 views

Custom functions in a REST API

Looking at two of our entities Company and Address. A company has a billingAddress and a profileAddress. I'm unsure of how to implement a function to set the billing address versus the profile. Here ...
4
votes
1answer
747 views

Authentication for users on a Single Page App?

I have developed a single page app prototype that is using Backbone on the front end and going to consume from a thin RESTful API on the server for it's data. Coming from heavy server side ...
4
votes
1answer
297 views

Data service API design

We're designing a data service that will store a large number of statistics about stocks, including historical data. The client will be a web application, which will need to pull various bits of data ...
4
votes
1answer
365 views

Is a PHP file secure enough on a GoDaddy Server to hard code an AES salt into the file?

So I am creating a web api for an app I am making. The data is sanitized before it is sent to my web api and then encrypted before it is stored in my MySql server. The phone app sanitizes then ...
3
votes
7answers
358 views

Better name for existsByUserNameAndPassword()

I wonder if there is a better name for a DB API function called existsByUserNameAndPassword() which returns boolean. There are more function called like this: existsByOldId()... It sounds a little bit ...