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
3answers
285 views

Best practice for a REST-ful API where objects would naturally have a “/” in their identifier

I am designing a REST api for a document management system. To make the API more natural, I thought about using the natural identifier for a file, which is it's path (usually having forward slashes "/"...
2
votes
2answers
297 views

Restful User/Password Authentication

I'm currently designing a REST-API with the following properties: Backend for a single page application (Later Apps) Integrated user database for each instance HTTPS/TLS only Authentication with ...
2
votes
5answers
111 views

Are there any downsides for the same API to perform two slightly different functions?

Take for example the following two GET requests with slightly different arguments: ../user/login_at which returns the last login date of the user, and ../user/login_at?start=2015-05-01&end=...
2
votes
1answer
504 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, ...
2
votes
3answers
599 views

Creating public API definition for existing application

Let's say there's a successful open source application (written in PHP if it matters), which provides its users with multiple ways to extend it (think about something like Drupal or Wordpress, lots of ...
2
votes
2answers
481 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} | |_ ...
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 ...
2
votes
3answers
1k views

One or many RESTful APIs for large company?

I work for a large company which has several non-RESTful APIs. I am tasked with building a web application to interact with these APIs. Each API handles and provides very different business processes ...
2
votes
3answers
1k views

Chain-of-Command/Responsibility pattern for my simple API. A good idea?

I need to write a simple API for a project I'm working on. This API will be used internally to perform some server side actions that were triggered by AJAX calls. To make things easier for me, I ...
2
votes
2answers
425 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 ...
2
votes
1answer
1k 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 ...
2
votes
4answers
763 views

Two libraries connecting to the database, leading to code smell?

In the current company that I work for there is a very large Utilities library. It was written a few years back (long before I joined) and has grown ergonomically over time to now do everything: ...
2
votes
2answers
163 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 ...
2
votes
4answers
485 views

What are some good ways to represent relationship among three numbers

I'm trying to find a clean, intuitive way to implement this problem. Basically, I have three numbers, and based on relationship (less than, greater than, and equal to) among these numbers would change ...
2
votes
1answer
88 views

How do I output an error when I'm determining how to output an error?

I've written an API which can be configured to signal errors in different ways (return values, debugging messages, or exceptions). I've got a check in place when the API is first initialized to see ...
2
votes
2answers
143 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 ...
2
votes
1answer
323 views

How should pagination allowing links to arbitrary pages be handled in a RESTful API?

How should a RESTful API handle pagination in the situation where a client may want the ability to jump to arbitrary pages? Let's assume we are using the Link header in the way the GitHub API does: ...
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 ...
2
votes
2answers
224 views

REST API Structure to request multiple items

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 ...
2
votes
4answers
334 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, ...
2
votes
1answer
296 views

How far to go when standardizing code [duplicate]

My small team and I have created a decent sized web application (~50k lines), with a fully featured API, all in Perl. As us perl hackers know.. it is easy to get sloppy. We had to port over a lot of ...
2
votes
1answer
2k views

Return values for CRUD methods?

I'm writing a basic web API in Java that does what almost all others do: take input, validate it, then do CRUD operations on the DB. I've written several APIs before, and I've pretty much already ...
2
votes
1answer
150 views

What are the guidelines for either throwing an exception or failing silently for nonvalid arguments? [duplicate]

If you look at XContainer.Add(object content) method you can see that id does not require content to be not null. It just does nothing in case of null. However List.AddRange(IEnumerable collection) ...
2
votes
1answer
124 views

Should I provide client libraries in some select languages along with the APIs themselves?

Say I have created a web service based on RESTful APIs. Does it make sense to also provide users with a client library for the API in some select languages which are likely to be the most used ones? ...
2
votes
1answer
36 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 ...
2
votes
1answer
145 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 ...
2
votes
1answer
167 views

Accessing internal API via Internal DMZ

I have an API that for firewall reasons can't sit on an internal DMZ and has to reside on the internal network. It was suggested that I build a 'shell' API that basically has all the same endpoints ...
2
votes
2answers
321 views

WCF service with methods to fetch data

I'm planning on building a WCF service that will fetch data entities from a Sql Server database. And I'm currently struggling with best practices issues. The thing is that there's a few different ...
2
votes
1answer
243 views

What is the idiomatic way in REST to handle field level permissions?

REST APIs conventionally expose resources addressed at the object level. While it's easy to do object level permissions using the appropriate HTTP responses, handling field level permissions is a bit ...
2
votes
2answers
236 views

Technique to synchronize error codes in a same-project-API

In the project I am working right now, we have some python and some C# code. At some point, I call from python a subprocess which starts a C# executable. This C# code returns an error code, which has ...
2
votes
1answer
410 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
449 views

Node.js API Architecture

I am currently working on a web app and want to design the interface between nodejs / mongoose and the backbone app. A short description of the app: A user signs up to the application and gets a ...
2
votes
1answer
296 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 ...
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 // ...
2
votes
1answer
774 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 ...
2
votes
1answer
130 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 ...
2
votes
1answer
2k 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 (...
2
votes
1answer
177 views

Design Application to “Actively” Invite Users (pretend they have privileges)

I am designing an application where users message one another privately, and may send messages to any Entity in the database (an Entity may not have a user account yet, it is a professional database). ...
2
votes
1answer
1k views

HTTP PHP Authentication and Android

I am working on a website for which I hope to have an application for as well. Because of this, I am creating PHP API's which will go into my Database and serve specific data based on the method/...
2
votes
1answer
1k views

Designing A 2-Way SSL RESTful API

I am starting to develop a WCF API, which should serve some specific clients. We don't know which devices will be using the API so I thought that using a RESTful API will be the most flexible choice. ...
2
votes
2answers
102 views

How should XML subtree manipulation be handled in a public API?

I'm working on an API whereby a specific call would replace a subtree of an XML document—rooted at some element—with another subtree. The two options I'm considering for a response to this call are: ...
2
votes
1answer
188 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 ...
2
votes
1answer
176 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 ...
2
votes
3answers
2k views

How to get different resources in a single endpoint in RESTful?

I have a REST webservice that have a couple of resources, like Company and User. But now I need to make a modification to the API to return a special list combining company, user and maybe other type ...
1
vote
2answers
308 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
3answers
122 views

Representing a “Belongs to” relationship in an API endpoint

Consider the following pseudo code models: class Post int Id string Title int CategoryId Category Category class Category int Id string Name Note that Post belongs to ...
1
vote
2answers
360 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
256 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 ...
1
vote
2answers
165 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. ...
1
vote
1answer
78 views

Web Routing Standards

We are putting together an API to provide our vendors some simplistic direct access. I've built APIs before, and have always routed them as such: {controller}/{action}/{id} My boss, however doesn't ...