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
2answers
157 views

Is it bad practice to use hyphens in JSON keys?

I see a lot of questions revolving around accessing JSON keys that use hyphens (kebab-case), but now I find myself wondering should I just stick to camelCase or snake_case in my keys. I know hyphens ...
1
vote
1answer
41 views

Class access modifiers on tested implementations

Suppose you're writing an interface that's suppose to be your public API, let's call it Session. It's implementation is called SessionImpl and it's going to be injected by your DI framework. I'm ...
8
votes
3answers
148 views

In REST parlance what is the difference between a resource and a representation?

My understanding of REST that is enables modelling service operations as representation of state and transition from one state to another making use of HTTP. I have always understood resources as ...
0
votes
1answer
54 views

Creating an API for existing products

Lately I've been searching for information about creating API's. The company I work for wants to sell some of our products as stand alone devices. Currently these products work inside enormous ...
3
votes
1answer
629 views

Merge two different API calls into One

I have two different apps in my django project. One is "comment" and an other one is "files". A comment might save some file attached to it. The current way of creating a comment with attachments is ...
9
votes
1answer
147 views

Idiomatic wrapping of C++ template type API in C

I'm working on wrapping a C++ API which provides access to a data store (Hazelcast) in C functions, so that the data store can also be accessed from C-only code. The Hazelcast C++ API for the Map ...
2
votes
1answer
34 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 ...
0
votes
0answers
80 views

How to limit api calls

I have following APIs in Node and I use Angular to consume the API. Each user is restricted to 100 news item. GET /news --> Get all the news GET /news/:id --> Get news with the id POST /news ...
9
votes
3answers
218 views

Breaking API changes: how can I make the transition easy for library users?

In the past, I used the standard way of adding @Deprecated annotations to API methods which will be removed in a later version. Now I am preparing a major version for a library, with many API parts ...
2
votes
1answer
151 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 ...
0
votes
0answers
34 views

How to manage Permissions for an api

I have a question about permissions and roles in an application. Let's assume app.get("/users",hasPermission("user:read"),...) and I have a lot of these calls and then a lot of permissions. How do I ...
3
votes
3answers
93 views

Is it possible to call a function or a script with a REST API?

Let us say that I want to create a workout app and a website, the user enters his workout stats and the app display his stats with graphs percentage and such. This is an example I don't want to ...
3
votes
1answer
60 views

RESTful API/Data Modeling - How to model an subordinate resource that will only ever have one element

I'm creating an API and data model for a multi-user document-creation application and I'm having trouble with a particular part of the data model/API design. Below is my current line of thinking: ...
1
vote
0answers
39 views

Why Does JavaFX's GridPane Attach Properties of the Layout to the Components?

I am currently learning JavaFX and I came across a very strange API for laying out GUI components. It is perhaps best explained by it's javadoc: To use the GridPane, an application needs to set ...
2
votes
4answers
326 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
0answers
43 views

Looking for pros/cons on using OWIN vs. a simple hand-rolled token based auth

We are wanting to implement an API to be used internally and externally and add it to our solutions. Some environment notes: We are currently using VS2013, .Net 4.5, EF5, SQL2008, MVC4, C#, and ...
1
vote
0answers
38 views

Should I use RFC 2119 in interface documentation?

RFC 2119 defines several terms, including MUST, SHOULD, and MAY, for use in standards documents, particularly those relating to networking protocols such as IP and HTTP. These terms are widely used ...
0
votes
1answer
46 views

Deciding on method idempotency approach

We are building a web service with an idempotent create method and we are looking for approaches on how to implement idempotency. The created objects have unique identifier properties, named Id, ...
1
vote
1answer
32 views

Which layer should convert timezones given querying on aggregate tables?

I'm running a Django application service with an API that feeds to a javascript frontend. The data is specifically for charts and graphs, so the data that is returned is a fairly large json with every ...
5
votes
2answers
1k views

“Invalid operation” status code in a HATEOAS REST API

In a HATEOAS API links are returned which represent possible state transitions. A conforming client should just be retrieving and following those links, but if a non-conforming client is constructing ...
0
votes
1answer
37 views

Bound Variadic Arguments: Bitmask vs Array

Intro The following assumes C# as a reference language, or any other statically typed language. This is not a question specific to Unity's API, but it is used as an example. In Unity's API, most ...
8
votes
2answers
276 views

How to handle complex calculated fields in an ORM

In our API we've got a few central datatypes which need to be "decorated" (so to speak) after retrieval from the database with calculated values. The database is accessed through an ORM which follows ...
4
votes
1answer
117 views

Boolean endpoint within a RESTful API

I am currently designing a JSON RESTful API which should have a boolean endpoint such as /item/vote which can either be false meaning that a user has not voted for a specific item or true meaning that ...
6
votes
1answer
119 views

Paging Strategies : Page Token vs Skip/Start Index

I am seeing that more and more new APIs use page tokens to let the user move between the pages of results containing a lot of items. However from an API designer point of view I'm not clear on what ...
3
votes
3answers
233 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 ...
4
votes
1answer
35 views

Restful user routes with web token

I'm trying to create an api which has a login that issues a JSON web token and then offers a handful of resources to authenticated requesters. User is a type of resource, and this is where I get ...
5
votes
2answers
173 views

How do I use checked exceptions without violating the Law of Demeter?

Given a language that enforces checked exceptions (let us assume Java), how do we design an API that can throw exceptions without violating the Law of Demeter? To put this question in the proper ...
3
votes
1answer
82 views

Should I be permissive of unknown parameters?

I'm designing a RESTful API and faced with the title problem, restated for clarity: Should I fail fast if a client sends an unrecognized parameter? For example, ...
1
vote
1answer
81 views

JsonAPI - Updating the relationship for a resource

I am having trouble understanding http://jsonapi.org/. Say, I have the following endpoints in my API for authors and articles. /authors /authors/:id/articles If I wanted to fetch the ...
1
vote
0answers
50 views

Design API for placing orders with differing parameters

Our customer wants to unify his ordering system, so that all of his end-customers can use one single website to place orders. The planned site will use web services to place the order in one of ...
3
votes
2answers
143 views

REST API - omitted properties in POST request: How should they be handled?

Given the following scenario: Teacher entity { "id": "1234", "name": "Mr. Didactic", "Subject": "History", "Classroom": "1A" } REST API endpoint: /teacher/id/1234 Let's say I submit ...
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 ...
1
vote
3answers
158 views

How far should I validate user input in my own created API?

I got something here that bogs my mind a bit. Let's say I write me this API (in TS), check out some of these properties: export class MyAPI{ ...
3
votes
5answers
129 views

Bulk update: return all results or only failures

I'm developing an API that performs bulk update of a large number of items in a single call. This code will consist of a REST endpoint and the internal library code that it calls. There are a few ...
2
votes
5answers
548 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 ...
1
vote
1answer
104 views

Richardson Maturity Level 3. What about form input

In many ways RMM level 3 is similar to the world wide web we know where every resource is available with the click of a link. In www we have links, but we also have forms where a form with ...
2
votes
2answers
126 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 ...
1
vote
1answer
60 views

Exposing blocking API in golang?

I have a golang library that abstracts a network service (think IRC-alike). The network server produces events which users of my library should consume. I'm using blocking network calls internally. I ...
1
vote
2answers
265 views

Design consideration on JSON schema for an API

I have an API endpoint that retrieve data from 3 SQL tables on the server-side. At the moment, I do a SELECT with joins, consolidate/reorganize the selected data based on a JSON schema, and then send ...
1
vote
1answer
306 views

Web Api design - Using Nouns vs verbs

I have this design situation at work. We have a internal Web-Api application and a Asp.Net Web forms application(UI). The web-application is calling Web-Api to update a Contractor. public Class ...
1
vote
1answer
82 views

Design - shallow routes for an API

I am building an API that will connect to multiple databases. I am using Emberjs on the front end and the default rest adapter seems to prefer shallow routes. Say, I have the following routes ...
3
votes
2answers
103 views

Status transitions with extra information in RESTful interfaces

How would you design a REST interface that triggers a status change of an object, but requires additional properties in that moment? For example, the deliverer of a package needs to change the status ...
6
votes
2answers
66 views

Library/API Runtime Between Versions

I was having a conversation with a friend about the C# StringBuilder class, and what it's behavior was. I'll paraphrase, but my side of the conversation was something like this (I oversimplified ...
0
votes
0answers
21 views

Relying on file hash for data synchronisation across mobile and server

Imagine a client-server app that lets user upload images/documents etc. to server and then lets users who have access, retrieve and view them later on their respective mobile devices. So the flow is ...
24
votes
7answers
2k views

Why use an opaque “handle” that requires casting in a public API rather than a typesafe struct pointer?

I'm evaluating a library whose public API currently looks like this: libengine.h /* Handle, used for all APIs */ typedef size_t enh; /* Create new engine instance; result returned in handle */ ...
0
votes
1answer
106 views

Strategy for Public / Private API, Encrypted (or Hashed) Data, and Server Compromise

In this very simplistic but realistic scenario, I have 2 combo web/database servers (A) behind a load balancer and a single IP address. They also permit access only from one IP address -- the client ...
29
votes
7answers
76k views

Why does java.util.ArrayList allow to add null?

I wonder why java.util.ArrayList allows to add null. Is there any case where I would want to add null to an ArrayList? I am asking this question because in a project we had a bug where some code was ...
6
votes
1answer
129 views

Why was conversion between Instant and Date named the way it was?

When Instant was introduced with JSR-310, convenience methods were added to perform conversion between Date and Instant: Date input = new Date(); Instant instant = input.toInstant(); Date output = ...
2
votes
2answers
305 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 ...
4
votes
1answer
227 views

Resource representations and REST API documentation tools

I find myself unsure about what exactly it means to have different representations of a RESTful resource. The canonical example is for an API to provide an endpoint - say /v1/users/:id - and allow ...