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

learn more… | top users | synonyms

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 ...
4
votes
2answers
860 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
235 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 ...
0
votes
2answers
708 views

How my website should use its own API?

Im building small web-service which will provide my users with data through API. Also, some data will be available right on my website. The question is about how to use my own API? Should my website ...
11
votes
2answers
3k 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
2answers
391 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 ...
0
votes
1answer
280 views

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

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
647 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
548 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 ...
2
votes
3answers
856 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 ...
23
votes
10answers
2k 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 ...
3
votes
1answer
423 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
134 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) ...
1
vote
2answers
256 views

In my permissions API, how do I handle objects that don't exist?

Elgg is designing a permissions API loosely around the Activity Streams model. The user API could look (roughly) like: function elgg_can($capability, $subject = null, $object = null, $target = null) ...
3
votes
3answers
758 views

API Development - Sinatra?

I've been tasked to create a mobile application as well as an accompanying website. Both the application and website will interact with the same database. To make things easy, I figure creating an API ...
6
votes
2answers
809 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 ...
0
votes
1answer
303 views

Best practices for deploying multilingual API

I have a hobby project and it looks like there is need to have some API library (which in turn is a wrapper over existing http API) at least for two languages - JavaScript and Python, adding support ...
4
votes
1answer
575 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 ...
2
votes
1answer
85 views

How do I output an error when I'm determining how to output an error?

I've written an API which can be configured to signal errors in different ways (return values, debugging messages, or exceptions). I've got a check in place when the API is first initialized to see ...
3
votes
3answers
319 views

Design for using your own API

So I'm planning to use APIs for my host app. But the APIs are built such that it requires a sessionkey for every request. So my question is, how would I dogfood my API? Cause, apparently I'm thinking ...
4
votes
1answer
2k views

Why does Android's Bundle API accept ArrayLists rather than Lists

I'm new to Android and while going through a tutorial on saving Activity state to a Bundle, I noticed that instead of accepting the more generic List interface, Bundle's put methods are expecting ...
9
votes
1answer
3k views

What is the proper way of nesting resources in REST model?

I'm designing a REST API of service and got stuck on proper way to nest resources. Resources: partners, tickets, settings Connections between resources: partner has many tickets, partner has set ...
0
votes
3answers
500 views

When there is no API

When it is necessary to integrate with a web application, and an API is unavailable, is it a viable solution to simulate a web browser interacting with the web application as a real user would ...
1
vote
3answers
1k views

How to get different resources in a single endpoint in RESTful?

I have a REST webservice that have a couple of resources, like Company and User. But now I need to make a modification to the API to return a special list combining company, user and maybe other type ...
2
votes
1answer
112 views

Should I provide client libraries in some select languages along with the APIs themselves?

Say I have created a web service based on RESTful APIs. Does it make sense to also provide users with a client library for the API in some select languages which are likely to be the most used ones? ...
2
votes
4answers
613 views

Two libraries connecting to the database, leading to code smell?

In the current company that I work for there is a very large Utilities library. It was written a few years back (long before I joined) and has grown ergonomically over time to now do everything: ...
13
votes
5answers
732 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 ...
0
votes
1answer
26k views

Difference between functional and technical specification [duplicate]

I'm writing a specification for a project, and am struggling with separating functional specification from technical specification (see http://www.joelonsoftware.com/articles/fog0000000035.html). ...
4
votes
2answers
1k 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 ...
8
votes
1answer
652 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 ...
3
votes
2answers
366 views

RESTful URI's, Creating a new noun/uri or add a queryparameter

I have a Person class with a one to many relationship to Employment. A Person in the CRM can have multiple Employments (historic data). My current REST URI for this class looks like this: ...
0
votes
2answers
318 views

How does API design differ from general web application development design? [duplicate]

If I was working on a web application designing and writing an API how does that differ from a general web application development? What things would I need to consider and take into account? Are ...
2
votes
2answers
335 views

Choosing between words with different spellings for function names

A question has been bothering me for a while: when developing international projects, it is common sense to use English as the reference language since it is the language that the most people ...
1
vote
2answers
213 views

Designing an API for service operations with closely related parameters

I'm having trouble deciding how to design this service API. public class GetCurrentValuesRequest { public int ReferenceID { get; set; } public int[] FilterIDs { get; set; } } public class ...
0
votes
4answers
465 views

C++ library API: new or getters?

I'm writing a C++ wrapper for my C library (my C++ skills are a bit rusty) and I'm wondering what's preferable: allowing user to construct objects themselves or give them objects via getters? What ...
1
vote
1answer
169 views

Storage Client Library 2.0 - Why is the API not as intuitive to use as 1.7?

I am migrating to using the new Storage Client Library for my Azure Table Storage. Querying with the previous Storage Client Library 1.7 namespace: var orders = serviceContext ...
7
votes
3answers
371 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, ...
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 ...
9
votes
1answer
5k 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: ...
0
votes
1answer
1k views

Configuration file for an API - should it be web.config? [on hold]

I have a remote procedure call API where the connection parameters need to be stored somewhere that the API code can access. This API is expected to be used mainly to create web services. I ...
5
votes
7answers
419 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 ...
2
votes
1answer
406 views

Node.js API Architecture

I am currently working on a web app and want to design the interface between nodejs / mongoose and the backbone app. A short description of the app: A user signs up to the application and gets a ...
10
votes
2answers
6k 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 ...
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 ...
16
votes
3answers
950 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 ...
0
votes
1answer
197 views

Rails-API gem, Is there such thing as an API only application?

I've built a few API's using the complete rails stack. In each project there have been multiple uses for rails core features. Each of the API has had management screens for monitoring usage, managing ...
6
votes
3answers
245 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, ...
5
votes
2answers
246 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 ...
1
vote
1answer
308 views

RESTful API design - should a PUT return related data?

I have an API which allows a user to update their system status; and a separate call to retrieve system status updates from other users. Would it make sense to unify them under a PUT request where a ...
8
votes
1answer
495 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 ...