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

learn more… | top users | synonyms

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
468 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
108 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
572 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
675 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
23k 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
976 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
641 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
357 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
303 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
322 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
209 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
449 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
167 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
348 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 ...
8
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
965 views

Configuration file for an API - should it be web.config?

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
410 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
391 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
920 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
186 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
234 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
236 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
283 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 ...
2
votes
3answers
128 views

Should static parameters in an API be part of each method?

I am currently creating a library that is a wrapper for an online API. The obvious end goal is to make it as easy for others to use as possible. As such I am trying to determine the best approach when ...
8
votes
1answer
458 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
2k 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 ...
6
votes
3answers
266 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 ...
5
votes
1answer
815 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 ...
5
votes
2answers
4k views

C++ Library API Design

I'm looking for a good resource for learning about good API design for C++ libraries, looking at shared objects/dlls etc. There are many resources on writing nice APIs, nice classes, templates and so ...
3
votes
1answer
281 views

When designing an enterprise API, what level is appropriate for separating libraries?

Assume we are developing a REST system for an enterprise company to expose the companies resources in a Java based application. Ultimately you have one web application, and domain libraries. My ...
4
votes
1answer
409 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 ...
7
votes
1answer
465 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 ...
2
votes
1answer
1k views

HTTP PHP Authentication and Android

I am working on a website for which I hope to have an application for as well. Because of this, I am creating PHP API's which will go into my Database and serve specific data based on the ...
5
votes
3answers
322 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 ...
2
votes
3answers
832 views

One or many RESTful APIs for large company?

I work for a large company which has several non-RESTful APIs. I am tasked with building a web application to interact with these APIs. Each API handles and provides very different business processes ...
3
votes
4answers
575 views

Should an API platform enforce only receiving JSON requests?

I am building an API platform. I have already ensured that the platform always returns JSON responses. My question is Should my API platform enforce the rule that all requests must be JSON? What ...
1
vote
2answers
197 views

What's the term for re-implementing an old API in terms of a newer API

The reason for doing it is to solve the case when a newer API is no longer backwards compatible with an older API. To explain, just say that there is an old API v1.0. The maker of this API decides it ...
1
vote
1answer
534 views

Securing Back End API for Mobile Applications

I have an application that I am writing for both iOS and Android; this application will be served by a ReSTFUL API running on a cluster of servers on "the internets". I am curious how the rest of the ...
1
vote
1answer
713 views

Designing A 2-Way SSL RESTful API

I am starting to develop a WCF API, which should serve some specific clients. We don't know which devices will be using the API so I thought that using a RESTful API will be the most flexible choice. ...
0
votes
3answers
1k views

Web API design best practices - having many (similar) operations

I have a web service (axis2) and the server performs 4 primary operations: createX, removeX, getX and updateX Where X is represented by a combination of 4 values: id1, id2, id3 and id4 So, to ...
3
votes
1answer
172 views

What are some good Photo and Artwork APIs?

We had an idea for starting a ecards service and were looking into the possibility of populating our site using photo/artwork APIs. Due to legal reasons, Flikr probably won't work, although I've ...
36
votes
3answers
6k 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 ...
5
votes
9answers
421 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 ...
1
vote
1answer
359 views

Request / Reply , how should one initiate the actual sending of the transmission?

I'm working on Language level interfaces to web API's. These libraries are of course built around existing HTTP Request/Reply interfaces. I see myself as having a few options submit method on the ...
3
votes
2answers
723 views

“Invalid operation” status code in a HATEOAS REST API

In a HATEOAS API links are returned which represent possible state transitions. A conforming client should just be retrieving and following those links, but if a non-conforming client is constructing ...