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

learn more… | top users | synonyms

1
vote
0answers
28 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 ...
2
votes
2answers
88 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 ...
1
vote
1answer
38 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 ...
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 ...
0
votes
3answers
133 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
108 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
485 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
94 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 ...
1
vote
1answer
22 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 ...
2
votes
2answers
69 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
36 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
236 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
261 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 ...
3
votes
1answer
523 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 ...
1
vote
1answer
62 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
99 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
60 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
18 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 ...
23
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
76 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 ...
25
votes
7answers
68k 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
126 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
83 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
99 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 ...
6
votes
1answer
172 views

How do you organize API endpoint contracts

Where trying to improve the "confidence" we have in our inter-service communication. Background: "Contracts" has been a matter of sharing a piece of code that defines an interface to implement, but ...
3
votes
1answer
101 views

why use authentication token instead of session_id for app(android side) in REST API

in normal php web application after login we use session_id that came from web browser to check if user loged in or not. But in REST API authentication I read some tutorials that say php should send ...
5
votes
2answers
300 views

Web Services and code lists

Our team heavily discuss the issues how to handle code list in a web service definition. The design goal is to describe a provider API to query a system using various values. Some of them are catalogs ...
12
votes
1answer
215 views

Maintain API vs. using idioms in a port

I'm working on a port from Python to Rust and ran into some code that can't be expressed as naturally in Rust as they can in Python. One case of this is using default parameters: class Foo: def ...
0
votes
1answer
75 views

Is it advisable to create a single API to access the database? [closed]

Got an organization that its core work is acquiring various sources of data, validating it and integrating it to existing mostly financial data sets and then availing that data to many different types ...
33
votes
14answers
17k views

RESTful API design. What should I return if there are no rows?

I'm currently coding an API for a social network with the Slim Framework. My question is: What are the best practices when there are no rows to return in the json structure? Lets say that this call ...
3
votes
2answers
80 views

How do I model a sortable resource in sql database? [closed]

I encounter this issue when I create REST API. I cannot tell the exact scenario, but let's say it is for a website that has category and product resources. Each category has many products and both ...
1
vote
3answers
189 views

Soap vs. rest - a hybrid approach? [closed]

I have a proper SOA architecture, with web services defined with WSDL and responding to SOAP requests. But this application has also an endpoint that responds to json request and replies in json ...
3
votes
2answers
186 views

Should I use my own public API for my web interface?

I am designing an API with django and its rest framework (and I am already not sure if it worth the hassle to version it or not). I totally know the iOS and Android apps will call the API, get a ...
29
votes
10answers
7k views

Why is Math.Sqrt() a static function?

In a discussion about static and instance methods, I always think, that Sqrt() should be a instance method of number types instead of a static method. Why is that? It obviously works on a value. // ...
0
votes
1answer
51 views

Should API DTOs be shaped to client(s) or be universal?

I have a project with an internal desktop client app and a server-side client API service talking to a relational database. I seem to have two choices: 1) shape DTOs to client views, e.g. ...
3
votes
3answers
191 views

How do I recreate this Access Control/Group/ whatever methodology in OO/MVC

I am looking at trying to rewrite an application that is mostly procedural to an MVC/OO approach in order to teach myself a deeper understanding of both. BUT, I am having some conceptual issues with ...
1
vote
0answers
42 views

Is it OK to use mongodb's query object format as a parameter for my api?

I am designing an api that can give developers read-only access to a large dataset. The data is stored in a mongodb database. All the results of the api, will basically either be a count of matches ...
2
votes
1answer
119 views

C++ HTTP API Design

I have a massive library written in C++ that handles a lot of mathematical operations, using C++ makes it fast and in all honesty, I don't want to re-write the whole functionality. I am thinking ...
1
vote
0answers
68 views

Alternatives to setting up an API system

I want to launch a service that could support integration by third-parties. Unfortunately it’s way out of hand to build an entire API by now. Here’s my question: Would there be any possible solution ...
2
votes
1answer
172 views

Writing a programming api for an existing project? [closed]

I've an already existing project in C#. Now I should implement a plugin system. For this plugin system I've to implement a programming api/sdk. I dont want, that plugins have access to the assemblies ...
0
votes
1answer
85 views

API Breaking Changes

I have a public REST API for creating new business profile records in my system. The request itself looks similar to this: { "BusinessName" : "AName", "CurrencyCode" : "USD" } You can see ...
2
votes
2answers
144 views

Create a globally visible method for an API

I'm trying to create a Java API that I will use in other projects. I understand that if I create new classes I can make objects in the other projects that have those classes. But what I want right ...
0
votes
1answer
210 views

How to avoid LazyInitializationException using Hibernate and Jersey

I am working with Spring Boot + Jersey + JPA/Hibernate to build a RESTful API. The issue I am encountering right now is when I have a relationship in my JPA Entity that is lazy loaded I get a lazy ...
3
votes
3answers
367 views

What are the advantages of dynamically binding a method to class instance? [closed]

I came across Instagram's API client written in Python. In their class InstagramAPI, they bind the methods to a function in bind.py. When called, the function returns an instance of the class ...
0
votes
1answer
128 views

Best way to separate public API from internal implementation [closed]

I'm developing a little framework (in Scala) where I want to define clean and simple interface for the users of the framework. Some of theses interfaces have to be implemented by the framework itself, ...
3
votes
5answers
2k views

API design pitfalls in C [closed]

What are some flaws that drive you nuts in C APIs (including standard libraries, third party libraries, and headers inside of a project) ? The goal is to identify API design pitfalls in C, so people ...
3
votes
4answers
149 views

What HTTP status using for REST search query which returns nos results

I'm wondering how to manage empty results returned by search queries in a REST web-service : I there was a query like my_ressource_collection/{id} and the resource didn't exists i would return 404 - ...
2
votes
1answer
225 views

Combining simple and complex APIs in a web application?

We use C# MVC and Angularjs as the primary tools to develop our web applications. We've recently been discussing best practices, with an eye towards revising our development approaches into something ...
4
votes
2answers
124 views

Rebol refinements vs. dialects vs. objects

I occasionally get conflicted when using a language that isn't Rebol (happens from time to time) and get to thinking, hm—would life be easier in Rebol if this thing worked this way? To illustrate my ...
2
votes
1answer
970 views

Does Java's Object.wait() really achieve nanosecond accuracy?

I was checking out the Java 8 standard library source code just out of curiosity, and found this in java/lang/Object.java. There are three methods named wait: public final native void wait(long ...