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

learn more… | top users | synonyms

3
votes
5answers
2k views

Why is the hashCode method usage of HashSet not specified in the API?

I was trying to debug my code which uses a HashSet and searching through the SO, I found out that I needed to override the hashCode method as well. The strange part is, checking the related API, I did ...
1
vote
0answers
34 views

Posting different-shaped json documents to the same resource in an API

Is it a good idea to create an API in such a way that clients can post different shaped JSON documents to the same Resource? Let me give you an example and and explanation to why I am asking this. I ...
3
votes
1answer
301 views

Should a web app for a service access its data via its own API or directly?

I'm building a service that will consist of mobile and desktop apps, which will require me to build my own RESTful web API to easily keep the data for the service in sync. I am also building a web ...
4
votes
2answers
208 views

Changing method signature while keeping backwards compatibility

I've inherited an API to maintain. Users can pass a callback function to the class which gets called on some event. The callback function is currently passed in a single argument. I need to change ...
3
votes
2answers
173 views

OO Design Question - Library/Objects for API which includes id references

Public api: getClients / getClientById - returns a json object like: { clientid: 1, name: "Client1" } getProjects / getProjectById - returns a json object like { projectid: 5, name: ...
24
votes
3answers
2k views

RESTful API: HTTP verbs with shared or specific URLs?

While creating a RESTful API, should I use HTTP Verbs on the same URL (when it's possible) or should I create an specific URL per action? For example: GET /items # Read all items GET ...
4
votes
2answers
304 views

How to safely chain several API requests for a single user

I am writing a web application with Python and Flask. At a high-level, the web service takes an ID, downloads a file from a third-party API based on that ID, reads and analyzes the data inside the ...
2
votes
2answers
385 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} | |_ ...
11
votes
1answer
1k views

Why PATCH method is not idempotent?

I was wondering about this. Suppose I have a user resource with id and name fields. If I want to update a field I could just do a PATCH request to the resource like this PATCH /users/42 {"name": ...
0
votes
1answer
117 views

What should my RESTful API method look like for a Roulette game?

I'm building a roulette game for fun, and the game will use a RESTful API. I'm building out the functionality for spinning the roulette wheel. I'm using MongoDB and have a collection for players _id ...
3
votes
1answer
243 views

A “Composite API” layer

We are giving services a complete overhaul at work: Swapping soap for rest, resculpting the domains to give better separation of concerns, etc. These new services will be publicly available. During ...
2
votes
2answers
373 views

Designing an API with access tokens, how to handle GET requests?

I am building an API that will utilize access tokens so that I can track usage among various departments and for access control. My plan is to utilize the HTTP verbs appropriately - GET will retrieve ...
0
votes
1answer
379 views

Sending multiple resources under REST endpoints

I am designing an API where- 1. There can be multiple devices under a gateway. 2. There are multiple sensors on every device. GET /devices/d1/sensors/s1 returns the status of sensor s1 on device ...
0
votes
1answer
48 views

Migrating single-layer ORM based app to multi-layer API

I'm trying to understand what is the best way of migrating a website that works in a single layer and gets all the data via an ORM, to one that uses multiple layers, using an API backend to get the ...
2
votes
3answers
412 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 // ...
5
votes
2answers
2k views

Why does java collections not supply a function for the index of max value?

I have been using Collections.max(list) for many projects, but I occasionally want to find the index of that maximum element. I feel silly writing a function to do this for myself in every program I ...
2
votes
1answer
221 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 ...
1
vote
2answers
160 views

WebAPI authorisation for other apps

I would like to create a WebAPI application that can serve some of my web sites. My goal is to abstract some common task such as email sending, address resolving etc by providing an API to all of my ...
3
votes
5answers
1k views

Storing a pointer to an argument passed by (non-const) reference

When designing an interface for passing objects which are meant to be stored for later use and which should not be 'null', I am always a bit uncertain if the argument should be passed by reference or ...
1
vote
0answers
200 views

API for accessing CTS and DSR signals of serial port [closed]

I'm trying to improve another abstraction of the serial port. The project involved often needs to check one of the single control signals CTS and DSR. This is currently done by a call to ...
-1
votes
1answer
49 views

API design: Giving the signin endpoint a noun name [closed]

Nouns are good and verbs are bad. HTTP codes + the endpoint /user/123 can signify user create, read, update and delete operations. But what should the signin and signout endpoint be called? How can ...
3
votes
3answers
197 views

Proper interface for calculator library?

As practice, I'm planning to implement a multivariable calculator library. The idea is that you can define a function, such as f(x, y) = sin(x)^2 + 3*y^3, and then you can evaluate it with specific ...
0
votes
1answer
1k views

REST API design for associations/aggregation

I am building RESTful API that manages persons and lists. There can be many List and many Person each with its own set of properties. Person can be in zero or more lists, List can contain zero or more ...
2
votes
2answers
892 views

Is RESTFUL API as back-end service one of the best (or suitable) choice for Mobile App? [closed]

I have a background on .NET development, recently I was asked to code back-end service for a mobile app. I had experiences on MVC, and now I'm trying to understand more on Restful Web API. My ...
2
votes
1answer
969 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 ...
1
vote
1answer
214 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
1answer
519 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 ...
4
votes
1answer
133 views

Should I add a key to the items of my REST API response?

I have an REST API endpoint which the JSON response looks like: { "products": [ {"id": 1040, "price": 2.95, ...} {"id": 4545, "price": 3.95, ...} ] } One of my colleagues ...
5
votes
3answers
1k views

How to handle business rules with a REST API?

I have a REST API to manage a booking system I'm searching how to manage this situation : A customer can book a time slot : A TimeSlot resource is created and linked to a Person resource. In order to ...
8
votes
2answers
233 views

As an API-user, would you tolerate BestPractice Exceptions?

I'm in the process of designing an API, part of which involves writing POCOs to a database. In C#, we have the DateTime structure. The "default" value for this (DateTime.MinValue) is 01/01/0001. ...
0
votes
1answer
329 views

Single page app permissions represented through RESTful APIs

I'm trying to figure out the right way to handle permissions in a single page app that talks directly to several RESTful APIs, that implement HATEOAS. As an example: "As a user of my application I ...
2
votes
1answer
123 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
2answers
189 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 ...
0
votes
3answers
432 views

Why do APIs generally consist of interfaces? [duplicate]

I am starting out in Java API design and in reading existing code bases, I have found that most APIs consist of interfaces only with their implementations bundled in a different package. Having read ...
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
412 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
364 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
200 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
157 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
490 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
133 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
3answers
269 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
143 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
501 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 ...
30
votes
5answers
8k 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
290 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
219 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 ...