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
0answers
50 views

Handle thousands of requests and reply after a fixed time with calculations using rails backend

I have a application which will get thousand of requests simultaneously and expect reply at the same time after a fixed period. I have decided to receive the requests and store the data in Redis and ...
0
votes
0answers
47 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: ...
20
votes
3answers
793 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 ...
2
votes
1answer
86 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
2answers
83 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} | |_ ...
3
votes
1answer
120 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
70 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 ...
1
vote
1answer
121 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
119 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
0answers
32 views

Java API initialization step

I am developing an Android Library which involves both Network and Bluetooth communication. In order to start using the library it must be configured. In other words a request to the backend must be ...
0
votes
0answers
28 views

How to Handle Multiple Versions of a REST API [duplicate]

At an interview I was asked the following question. You are giving out a rest API and you know that there will be multiple versions of it. The API methods will remain the same across versions but the ...
0
votes
1answer
48 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
0answers
22 views

Add new/modify existing callback to/in API

I am working on a common API for a user interface. My colleagues use this framework in all their projects, but the UI is not our main aspect here, so the knowledge of the UI framework is somewhat ...
0
votes
1answer
27 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 ...
1
vote
3answers
315 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
453 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
117 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
1answer
83 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
4answers
198 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 ...
0
votes
0answers
47 views

API for accessing CTS and DSR signals of serial port

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
43 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 ...
2
votes
3answers
131 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
156 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 ...
1
vote
2answers
167 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
0answers
56 views

Single result as REST/ODATA response on GET

In an API which should be both restful and support OData for different client types. I have an endpoint that always returns a single result. Should I: Return the entity as a single entity? Put it ...
1
vote
1answer
149 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, ...
1
vote
1answer
48 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
98 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
323 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
215 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
110 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
87 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
91 views

REST API Structure

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
308 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
245 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 ...
0
votes
0answers
39 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
107 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
140 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
613 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
149 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
109 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
103 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
97 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
101 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 ...
0
votes
0answers
37 views

What is the best solution for an API class that could have different end points? (iOS)

What is the best approach for creating a singleton API class, where different requests could call different api providers and how to manage this? For instance you might have a singleton class 'API' ...
5
votes
4answers
446 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 ...
19
votes
5answers
2k 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
168 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
148 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 ...