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

learn more… | top users | synonyms

2
votes
5answers
614 views

API design dilemma: to REST or not to REST

I'd like to design a REST API supporting: Login Temporary token generation The reason being there are a number of client-side REST libraries that would speed up development if used, as they take ...
2
votes
1answer
43k 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). ...
2
votes
4answers
189 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 ...
2
votes
3answers
306 views

Best practice for a REST-ful API where objects would naturally have a “/” in their identifier

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/"...
2
votes
2answers
313 views

Restful User/Password Authentication

I'm currently designing a REST-API with the following properties: Backend for a single page application (Later Apps) Integrated user database for each instance HTTPS/TLS only Authentication with ...
2
votes
5answers
112 views

Are there any downsides for the same API to perform two slightly different functions?

Take for example the following two GET requests with slightly different arguments: ../user/login_at which returns the last login date of the user, and ../user/login_at?start=2015-05-01&end=...
2
votes
1answer
527 views

Does ORM at any point become a “requirement” for RESTful API?

I've started building a RESTful API in PHP's Slim framework. The framework appealed to me because of its light-weight design and routing features. I am using PostgreSQL for the database. However, ...
2
votes
3answers
600 views

Creating public API definition for existing application

Let's say there's a successful open source application (written in PHP if it matters), which provides its users with multiple ways to extend it (think about something like Drupal or Wordpress, lots of ...
2
votes
2answers
495 views

How to deal with multiple “entry points” for an action in a REST API?

Let's say we have two kinds of resources, user and group. Every user can belong to multiple groups and each group can have many members. Thus I can model my API like this / |_ /users/{id} | |_ ...
2
votes
1answer
274 views

Gradual reveal in REST APIs [closed]

In the article Building Web Services the REST Way, the author states: Design to reveal data gradually. Don't reveal everything in a single response document. Provide hyperlinks to obtain more ...
2
votes
3answers
1k 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 ...
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 ...
2
votes
2answers
578 views

How to correctly implement key=value storage REST API

I'm new to REST API, so I decided to get familiar with it by designing a small web service API. I have its design written down and would like you to review it. I feel like I have made some mistakes in ...
2
votes
1answer
1k views

Does Java's Object.wait() really achieve nanosecond accuracy?

I was checking out the Java 8 standard library source code just out of curiosity, and found this in java/lang/Object.java. There are three methods named wait: public final native void wait(long ...
2
votes
4answers
780 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: ...
2
votes
2answers
166 views

Create a globally visible method for an API

I'm trying to create a Java API that I will use in other projects. I understand that if I create new classes I can make objects in the other projects that have those classes. But what I want right ...
2
votes
4answers
493 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 ...
2
votes
1answer
90 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 ...
2
votes
3answers
204 views

How to design a REST API to handle non-CRUD operations?

I'm trying to convert a set of SOAP-based services to a RESTful API. I started by identifying resources by analyzing operation names and I got the resource Subscription. When I need to update the ...
2
votes
2answers
170 views

REST API - Handling subresources

Suppose there is a primary resource "/accounts" which has Profile (name, national id, DOB), addresses and contacts(email, phones). I am considering them as sub-resources because they cannot exist ...
2
votes
1answer
336 views

How should pagination allowing links to arbitrary pages be handled in a RESTful API?

How should a RESTful API handle pagination in the situation where a client may want the ability to jump to arbitrary pages? Let's assume we are using the Link header in the way the GitHub API does: ...
2
votes
3answers
104 views

Handle server-side/client-side when for showing missing information as placeholders

I have a database table which stores Incident details. Each Incident can have an image saved for it. There are some Incidents which will not have an image for it. I have an API which pulls the image ...
2
votes
1answer
271 views

Should I separate a web api from the webserver?

Lets say I'm building a site similar to this or Quora (or some arbitrary blog-like site). I need a real-time component that will be using web-sockets/long-polling to notify the user of new posts, ...
2
votes
2answers
237 views

REST API Structure to request multiple items

I have a REST API that looks something like the below where a person can belong to an organisation (but doesn't have to) and a person has many items. The items may also belong to the organisation ...
2
votes
4answers
345 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, ...
2
votes
1answer
304 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 ...
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 ...
2
votes
1answer
150 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
1answer
125 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
1answer
38 views

Configuration related defines in public header?

Suppose you're building some library, C or C++ doesn't really matter for this question, IMO. The features (or implementation thereof) depend on capabilities of the target system. A simple, probably ...
2
votes
1answer
146 views

C++ HTTP API Design

I have a massive library written in C++ that handles a lot of mathematical operations, using C++ makes it fast and in all honesty, I don't want to re-write the whole functionality. I am thinking ...
2
votes
1answer
192 views

Accessing internal API via Internal DMZ

I have an API that for firewall reasons can't sit on an internal DMZ and has to reside on the internal network. It was suggested that I build a 'shell' API that basically has all the same endpoints ...
2
votes
2answers
347 views

WCF service with methods to fetch data

I'm planning on building a WCF service that will fetch data entities from a Sql Server database. And I'm currently struggling with best practices issues. The thing is that there's a few different ...
2
votes
1answer
253 views

What is the idiomatic way in REST to handle field level permissions?

REST APIs conventionally expose resources addressed at the object level. While it's easy to do object level permissions using the appropriate HTTP responses, handling field level permissions is a bit ...
2
votes
2answers
246 views

Technique to synchronize error codes in a same-project-API

In the project I am working right now, we have some python and some C# code. At some point, I call from python a subprocess which starts a C# executable. This C# code returns an error code, which has ...
2
votes
1answer
429 views

Trying to process partial POST of data in REST when some data is successful?

I have a resource that accepts array of numbers. Each number is proceed interdependently, and computation fails are expected. How should I communicate to API client "some of your numbers couldn't be ...
2
votes
1answer
451 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 ...
2
votes
1answer
67 views

API Design: How to Specify an Arbitrary Tree?

I'm writing an API, in which one of the function calls of which is meant to be a call to a factory for a series of tree nodes that take a number of parameters, some of which are the same and some of ...
2
votes
1answer
307 views

Combining simple and complex APIs in a web application?

We use C# MVC and Angularjs as the primary tools to develop our web applications. We've recently been discussing best practices, with an eye towards revising our development approaches into something ...
2
votes
3answers
413 views

Which one of these would be the better way to implement object copying in c#?

I would like to be able to copy an object and only change a few values. I have come up with two different ways to do this. // OPTION A - create a copy constructor and use property // ...
2
votes
1answer
845 views

How should data transfer between a client and a web API for normalized data be designed?

I want to design an API backed by some database (doesn't really matter which, but to make the discussion more interesting, let's say it's Mongo - explanation below) which sends data to a client. The ...
2
votes
1answer
132 views

Python API: Extension Module or Pure Module

We have a C++ application, with C++ interfaces changing regularly during development. We also have a C API which is designed to be stable in spite of such changes; the C API is tighly focused on ...
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 (...
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). ...
2
votes
1answer
2k 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 method/...
2
votes
1answer
1k 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. ...
2
votes
2answers
102 views

How should XML subtree manipulation be handled in a public API?

I'm working on an API whereby a specific call would replace a subtree of an XML document—rooted at some element—with another subtree. The two options I'm considering for a response to this call are: ...
2
votes
1answer
81 views

REST API design: distinction between searching and getting all instances of a resource

At the moment, my (pretty standard) REST interface looks like this: POST /foo # creates a new foo PUT /foo/{id} # updates a specific foo GET /foo/{id} # returns a specific foo GET /...
2
votes
0answers
20 views

Storing OAuth2 data in Mongo?

Our system has users but we want to perhaps allow some users to be able to use our API service. I'm looking at using OAuth2 for authorization. As it's going to be (trusted) machine-to-machine access I ...
2
votes
1answer
229 views

Is there a design pattern to handle construction of complex objects with a [1 → 1..*] multiplicity relationship?

I have two classes (A and B) that are both complex to construct, with multiple properties that must be validated at construction time. I want to use the Builder pattern to construct these objects, but ...