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

learn more… | top users | synonyms

0
votes
1answer
110 views

Why does this API include a static “kind” parameter in the request and response?

I am looking at the Google QPX Express API and noticed that each group of parameters includes a kind parameter that is set to a specific string. For example, on the request: { "request": { "...
4
votes
2answers
364 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 ...
1
vote
1answer
145 views

Do RESTful API controllers typically only provide resources related to their own type?

Let's say my API has the following routes: GET /theaters GET /theaters/:id GET /theaters/:id/movies GET /movies GET /movies/:id GET /movies/:id/theaters And then I have the following controllers ...
2
votes
1answer
412 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
507 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, ...
3
votes
1answer
234 views

Web API Design advice

I am developing a Web API as services layer for a ASP.NET web forms application. There are two controllers ContractorController (gives details about the contractor) and PaymentsController (gives ...
1
vote
2answers
62 views

HTTP status code for mobile clients

There was a debate with one of the platform engineers (as a mobile dev), about the codes being returned. The scenario is: when trying to create a resource the server is returning a 201 with the ...
12
votes
6answers
6k views

Should an Http API always return a body?

Is there some sort of standard regarding http api responses? After reading this discourse thread I started to wonder. We are developing our public http json api at my work, and we do not return ...
1
vote
2answers
56 views

Using many Resource URI to create a Record and handling failure

Hi Guys, I have a decision to make to solve a problem, I’m describing the problem below. Application Overview I have an ASP.NET MVC 4 webApp which uses Rest Api for almost all the tasks, from Login ...
1
vote
2answers
310 views

Is it better to perform a calculation in the field's setter or have a different method?

I'm implementing a simple Quota object which determines a usage percentage based on the maximum and the used. private int maximum; private int used; public Quota(int used, int maximum) { this....
1
vote
1answer
93 views

Best way to keep consistent data in model across devices?

I have a model for an app that is fairly large, all of which needs to be on a users' device at the same time. For example, a spreadsheet. If a user makes a change to the model on one device, I want ...
1
vote
0answers
57 views

Individual methods or parameters for Google Analytics abstraction on Android

A coworker and I are having a discussion around the best way to build our abstraction on top of Google Analytics for an Android application. A couple of data points. We have auto-tracking enabled ...
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 ...
4
votes
4answers
2k views

int * vs int [N] vs int (*)[N] in functions parameters. Which one do you think is better?

When programming in C (or C++) there are three different ways to specify the parameter in a function that takes an array. Here is an example (implementing std::accumulate from C++ in C) that shows ...
2
votes
1answer
266 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 ...
4
votes
1answer
632 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
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 // ...
1
vote
0answers
279 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 $http....
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
102 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
6k 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
38 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
287 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
387 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
153 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
322 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 ...
2
votes
2answers
483 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
127 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
520 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
550 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 d1....
0
votes
1answer
54 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
499 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
246 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
51 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
989 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
260 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
777 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
411 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
131 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
230 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
458 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
214 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 ...