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

learn more… | top users | synonyms

2
votes
0answers
39 views

REST API design: distinction between searching and getting all instances of a resource

At the moment, my (pretty standard) REST interface looks like this: POST /foo # creates a new foo PUT /foo/{id} # updates a specific foo GET /foo/{id} # returns a specific foo GET /...
7
votes
1answer
249 views

Why are checked vs. unchecked exceptions called “the controversy” in Oracle Java tutorial?

I am new to Java and was reading its documentation on exceptions., and especially the Unchecked Exceptions — The Controversy page. The bottom-line says: If a client can reasonably be expected to ...
5
votes
1answer
126 views

By the book REST vs Too Many Requests

From Roy Fielding's comment on his own article decrying fake REST apis: A truly RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g....
0
votes
0answers
45 views

POST REST api request parameter structure

I am working on building a REST api for a web service which aggregates results from multiple backend systems. The current structure is the following { "query" : "test", "sources": [backend1, ...
3
votes
3answers
126 views

What is the advantage of API clients

At my new job I am working on a basic existing CRUD web application in MVC + with an angular front-end. The MVC API has a swagger spec and it's used to generate an API client with auto rest. That API ...
1
vote
4answers
210 views

MVC and RESTful API service

MVC is pretty straightforward. There is a Model, a Controller and a View. When we create a website, it all come together as 'client sends REST keyword request to server -> the server matches the ...
2
votes
1answer
67 views

API Design: How to Specify an Arbitrary Tree?

I'm writing an API, in which one of the function calls of which is meant to be a call to a factory for a series of tree nodes that take a number of parameters, some of which are the same and some of ...
0
votes
1answer
103 views

What is the best way to publish a REST API so that other people can see and improve/add new methods on it?

I have a requirement to (re)design an existing REST API which is written in Django REST. One of the main requirements is allowing third parties, approved by us, extending of our API. The API is a ...
1
vote
2answers
92 views

What API design makes the most sense for changing a user's password?

Consider a web page where a user changes his password after clicking on an emailed password reset link. The page will be implemented against an API using ajax, rather than as an ordinary form ...
1
vote
3answers
100 views

REST API - proper way to handle non-CRUD items with REST

So, there are many times where I have to do things with my REST API that seem outside the boundaries of REST. In this particular instance I need to have an endpoint that checks whether a member is ...
1
vote
1answer
45 views

Specialized API endpoints or multiple calls to generic resources?

This problem came up while designing the API for a SPA web application, which communicates with the server via AJAX. On one page the user, who is creating a list of people to invite to an event, has ...
0
votes
0answers
23 views

Volley with AsyncTask

I'm developing an Android library so that other apps would use, which is a kind of an API 'driver', to be used with an external services API and contains also UI components. On most of the requests ...
2
votes
3answers
201 views

How to design a REST API to handle non-CRUD operations?

I'm trying to convert a set of SOAP-based services to a RESTful API. I started by identifying resources by analyzing operation names and I got the resource Subscription. When I need to update the ...
4
votes
3answers
80 views

GET resource state with JSON body or HTTP code

I want to provide rest api for my iot service to read state of a sprinkler on/off. So far I've come up with two solutions: GET /api/sprinkler that returns 204 if on and 404 if off GET /api/sprinkler ...
2
votes
0answers
20 views

Storing OAuth2 data in Mongo?

Our system has users but we want to perhaps allow some users to be able to use our API service. I'm looking at using OAuth2 for authorization. As it's going to be (trusted) machine-to-machine access I ...
1
vote
0answers
66 views

How do I write an API that makes use of many smaller APIs?

I have a solid set of classes that do the following build tables from data and templates advanced form serialization build forms from data and templates launch overlays with forms/wizards short poll ...
1
vote
1answer
119 views

Polymorphic constants in Java

I am designing some polymorphic code to perform mathematical operations. The idea is to abstract out the underlying representation of the data, as different use cases require different representations....
5
votes
1answer
94 views

One Large API to several microservices vs lots of small APIs each with their own API

I have an application that is beiong split out into a number of services. From a previous question on here, I think that initially JSON/REST is the way to go for communication. Some of my micro ...
3
votes
1answer
132 views

In Java, why is there no instance method like bigDecimal.isGreaterThan(otherBigDecimal)?

The current way of knowing if a BigDecimal is greater than another is bigDecimal.compareTo(otherBigDecimal) > 0 (or one.compareTo(another) == 1), but I find it too clunky and unexpressive. ...
1
vote
2answers
185 views

API Design: Should I use strings or an enum for dictionary keys

I am working on an API in C#. I am trying to think about the simplest way to expose my API for consumers of it. In particular, I have a class in my exposed data model that has a dictionary property. ...
0
votes
0answers
15 views

Using JWT over Oauth2.0

I am creating an API that will communicate with a ReactJS app. I am in two minds whether to go through with the implementation of OAuth2.0. The question is why should I use OAuth2.0 implicit grant ...
1
vote
3answers
223 views

What is wrong with treating a client session as a resource/application state in REST architecture?

Given these example REST API / HATEOAS applications: InfoQ How to GET a Cup of Coffee example Java Spring REST API example ... where POST/PUT/PATCHING resources clearly alters the state/...
5
votes
1answer
88 views

Designing a flexible API with support for Callbacks

I am writing a Java library that needs to make http GET && POST requests. There will be two types of users of this library: Those with understanding of callbacks and know how to use them. ...
9
votes
4answers
506 views

Dependency Inversion expands the API, results in unnecessary tests

This question has bothered me for a few days, and it feels like several practices contradict each other. Example Iteration 1 public class FooDao : IFooDao { private IFooConnection fooConnection;...
4
votes
2answers
282 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 ...
0
votes
1answer
62 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 ...
8
votes
3answers
188 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 ...
2
votes
1answer
38 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
92 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
230 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 ...
0
votes
0answers
35 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 ...
9
votes
1answer
164 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 ...
3
votes
3answers
103 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 ...
1
vote
0answers
60 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 ...
3
votes
1answer
101 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: ...
0
votes
0answers
57 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 asp....
1
vote
0answers
40 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
53 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
35 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 ...
0
votes
1answer
40 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 ...
4
votes
1answer
269 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
151 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 ...
4
votes
1answer
36 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
191 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
105 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, http://example.com/api/foo?bar=true&...
1
vote
1answer
131 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
188 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 ...
2
votes
1answer
225 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 ...
1
vote
3answers
159 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{ propertyThatShouldContainSuffix:Array<...