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

learn more… | top users | synonyms

4
votes
1answer
599 views

Using macros to protect assignment to global variables

Because there is no language feature in C to protect assignment to global variables would you recommend doing something like this? Take this example: We have a module with the header file called ...
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 // ...
1
vote
0answers
273 views

How can I use protected Tastypie resources within Angular?

I have a working Django 1.7 project with an API (Tastypie) made available for mobile clients (ApiKeyAuthentication). I am using Angular with Chart.js, and so I need to GET some queryset using ...
3
votes
1answer
93 views

What is the correct way to publish a runtime? Should it be a singleton?

I have a compiler for a programming language that targets JavaScript. That language needs some global functions such as: alloc, memcpy, write and so on. My question is: where should I position those ...
2
votes
3answers
99 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 ...
15
votes
4answers
5k views

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

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 ...
1
vote
0answers
37 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 ...
4
votes
2answers
272 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
1answer
373 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
1answer
151 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 ...
0
votes
1answer
314 views

REST and RPC in multi-tier API

My team is developing a multi-tier API with scalability and modularity in mind. The public access point of the API is fully REST. However, we are splitting the data access layer as another tier in our ...
78
votes
3answers
17k 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 ...
2
votes
2answers
466 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} | |_ ...
15
votes
1answer
2k 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
125 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
2answers
473 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
525 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
52 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 ...
5
votes
2answers
3k 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 ...
4
votes
1answer
478 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
233 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
50 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
2answers
971 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 ...
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 ...
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 ...
1
vote
1answer
249 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
722 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 ...
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. ...
1
vote
1answer
390 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
128 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 ...
1
vote
1answer
220 views

How to create Public API wrapper with different configuration parameters

I'm looking to see if there is a design pattern that can solve the following problem. The example is fairly specific but the goal is a public + internal API. I need specific information for my ...
0
votes
3answers
451 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 ...
1
vote
2answers
225 views

Accepting a numerical range in a function call

I have encountered two ways of doing it: void foo(int from, int to); /* 'from' inclusive, 'to' exclusive */ void foo(int startIndex, int rangelength); Has one style historically been preferred ...
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 ...
3
votes
1answer
212 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 ...
1
vote
0answers
43 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
432 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 ...
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
159 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 ...
5
votes
2answers
2k views

How to handle fine grained field-based ACL permissions in a RESTful service?

I've been trying to design a RESTful API and have had most of my questions answered, but there is one aspect of permissions that I'm struggling with. Different roles may have different permissions ...
0
votes
3answers
585 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
143 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: ...
0
votes
1answer
172 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
523 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 ...
40
votes
5answers
12k 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
348 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
246 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 ...
42
votes
6answers
5k 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 ...
1
vote
2answers
283 views

Returning view code in an API response

I have an API that returns a JSON formatted array of users within a given pair of lat/ long bounds. I'm using this data to plot a number of markers on a map, based on the location of each user. I ...
1
vote
2answers
3k views

How to avoid unauthorized use of an API?

I have to design a "widget", a script that partners will embed in their websites to display some UI and make calls to our API. Basically it will display our data on these sites based on some IDs they ...