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

Accepting a numerical range in a function call

I have encountered two ways of doing it: void foo(int from, int to); /* 'from' inclusive, 'to' exclusive */ void foo(int startIndex, int rangelength); Has one style historically been preferred ...
1
vote
2answers
47 views

HTTP status code for mobile clients

There was a debate with one of the platform engineers (as a mobile dev), about the codes being returned. The scenario is: when trying to create a resource the server is returning a 201 with the ...
1
vote
2answers
114 views

When writing a library or an API, when should and when shouldn't I validate or automatically correct errors in data provided by another developer?

I have a fairly good understanding of when data validation should and shouldn't exist when it comes when writing an application that is only dealt with by an end-user, and all the different tiers of ...
1
vote
1answer
66 views

REST API, nested routes without providing identifiers at every nested level

Obviously a RESTful API could contain base routes such as: api/competitions api/competitions/{id} api/teams api/teams/{id} api/players api/players/{id} And nested routes such as: ...
1
vote
2answers
147 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 ...
1
vote
2answers
206 views

Returning view code in an API response

I have an API that returns a JSON formatted array of users within a given pair of lat/ long bounds. I'm using this data to plot a number of markers on a map, based on the location of each user. I ...
1
vote
1answer
295 views

RESTful API design - should a PUT return related data?

I have an API which allows a user to update their system status; and a separate call to retrieve system status updates from other users. Would it make sense to unify them under a PUT request where a ...
1
vote
1answer
81 views

Correct approach for creating api contract

I need help regarding below: I am trying to design an API. For creating contracts below are the two approaches: Approach 1: public class MyController { public void MyAction1(Dictionary<string, ...
1
vote
1answer
88 views

REST - Recommendation route: POST or GET?

I'm building an api route which will pull data from our server. This data is sorted in an arbitrary (changing and unknown to the client manner), and will never return the same data more than once. ...
1
vote
2answers
1k views

REST API - Should API Return Nested JSON Objects?

When it comes to JSON APIs is it good practice to flatten out responses and avoid nested JSON objects? As an example lets say we have an API similar to IMDb but for video games. There are a couple ...
1
vote
2answers
42 views

Using many Resource URI to create a Record and handling failure

Hi Guys, I have a decision to make to solve a problem, I’m describing the problem below. Application Overview I have an ASP.NET MVC 4 webApp which uses Rest Api for almost all the tasks, from Login ...
1
vote
1answer
172 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
3answers
377 views

C API in C++ with RAII, two alternatives to implement error handling (Exceptions)

I have an API written in C, which produces a result by returning a pointer to allocated memory. For using it with C++ (C++11) I've wrapped the function calls in objects, which keep the result in a ...
1
vote
2answers
87 views

API for expanation of complicated calculation or business rules?

In online shops there are areas with complicated rules. For example is a product visible in the product catalog is a product sold out what is the price for the product (Discounts, Promotions, ...) ...
1
vote
2answers
212 views

Designing an API for service operations with closely related parameters

I'm having trouble deciding how to design this service API. public class GetCurrentValuesRequest { public int ReferenceID { get; set; } public int[] FilterIDs { get; set; } } public class ...
1
vote
1answer
59 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 ...
1
vote
1answer
47 views

Best way to keep consistent data in model across devices?

I have a model for an app that is fairly large, all of which needs to be on a users' device at the same time. For example, a spreadsheet. If a user makes a change to the model on one device, I want ...
1
vote
1answer
120 views

How to create Public API wrapper with different configuration parameters

I'm looking to see if there is a design pattern that can solve the following problem. The example is fairly specific but the goal is a public + internal API. I need specific information for my ...
1
vote
2answers
113 views

Is there a way to efficiently allow a user to upload multiple content at once for e-commerce type sites?

Sellers on large sites like Amazon and Newegg need to provide names, descriptions, and images for their products to be displayed on the e-commerce sites. These sellers could have 10000+ products to ...
1
vote
2answers
687 views

Do I need to return error: null in JSON response?

When designing a RESTful API that uses JSON to respond to requests, I usually return an object like this when an error happens: { "error": "Something bad happened", "error_code": "XXX" } Do I ...
1
vote
2answers
253 views

In my permissions API, how do I handle objects that don't exist?

Elgg is designing a permissions API loosely around the Activity Streams model. The user API could look (roughly) like: function elgg_can($capability, $subject = null, $object = null, $target = null) ...
1
vote
1answer
544 views

Securing Back End API for Mobile Applications

I have an application that I am writing for both iOS and Android; this application will be served by a ReSTFUL API running on a cluster of servers on "the internets". I am curious how the rest of the ...
1
vote
1answer
730 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. ...
1
vote
1answer
366 views

Request / Reply , how should one initiate the actual sending of the transmission?

I'm working on Language level interfaces to web API's. These libraries are of course built around existing HTTP Request/Reply interfaces. I see myself as having a few options submit method on the ...
1
vote
1answer
178 views

How do you deal with errors in enumeration / list processing (lowish-level API)

Ive struggled with variants of this problem many times, experimenting with different solutions, happy with none. Abstract: Enumerating a list of items, an error for one item does not affect the ...
1
vote
1answer
25 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 ...
1
vote
1answer
67 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
0answers
149 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
0answers
43 views

Individual methods or parameters for Google Analytics abstraction on Android

A coworker and I are having a discussion around the best way to build our abstraction on top of Google Analytics for an Android application. A couple of data points. We have auto-tracking enabled ...
1
vote
0answers
222 views

How can I use protected Tastypie resources within Angular?

I have a working Django 1.7 project with an API (Tastypie) made available for mobile clients (ApiKeyAuthentication). I am using Angular with Chart.js, and so I need to GET some queryset using ...
1
vote
0answers
28 views

Posting different-shaped json documents to the same resource in an API

Is it a good idea to create an API in such a way that clients can post different shaped JSON documents to the same Resource? Let me give you an example and and explanation to why I am asking this. I ...
1
vote
0answers
76 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: ...
1
vote
0answers
123 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
vote
0answers
40 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 ...
1
vote
3answers
1k 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
1answer
167 views

Storage Client Library 2.0 - Why is the API not as intuitive to use as 1.7?

I am migrating to using the new Storage Client Library for my Azure Table Storage. Querying with the previous Storage Client Library 1.7 namespace: var orders = serviceContext ...
1
vote
2answers
658 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
3answers
488 views

When there is no API

When it is necessary to integrate with a web application, and an API is unavailable, is it a viable solution to simulate a web browser interacting with the web application as a real user would ...
0
votes
1answer
24k views

Difference between functional and technical specification [duplicate]

I'm writing a specification for a project, and am struggling with separating functional specification from technical specification (see http://www.joelonsoftware.com/articles/fog0000000035.html). ...
0
votes
4answers
227 views

API naming and namespacing [on hold]

Is it right or more beautiful to name the functions with an prefix, like in Qt? Or using "many" namespaces, but 'normal' names for functions? For example, slOpenFile(); //"sl" means "some lib" vs ...
0
votes
4answers
457 views

C++ library API: new or getters?

I'm writing a C++ wrapper for my C library (my C++ skills are a bit rusty) and I'm wondering what's preferable: allowing user to construct objects themselves or give them objects via getters? What ...
0
votes
2answers
103 views

Idiomatic C API with regards to pointers

I am trying to get a better understanding of how one would structure an API in C. I create a struct Person I have a init function that sets data on that struct I have multiple "helper" functions ...
0
votes
3answers
364 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 ...
0
votes
2answers
81 views

How should an API or server respond when a device connects with a different account than it is bound to?

In my system we have users accounts and user devices. Rules: A user can have only one user account. Each user can have many devices. A device can be bound to only one user account. Upon initial ...
0
votes
2answers
681 views

How my website should use its own API?

Im building small web-service which will provide my users with data through API. Also, some data will be available right on my website. The question is about how to use my own API? Should my website ...
0
votes
3answers
1k views

Web API design best practices - having many (similar) operations

I have a web service (axis2) and the server performs 4 primary operations: createX, removeX, getX and updateX Where X is represented by a combination of 4 values: id1, id2, id3 and id4 So, to ...
0
votes
1answer
102 views

best way to export binary data with additional text attributes to a stream

I would like to create a command line API in a Java application to export a binary blob to stdout. I would additionally like to export certain attributes about the blob, ideally in a non-binary ...
0
votes
1answer
199 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
3answers
272 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. ...
0
votes
1answer
167 views

How does public API designer come to the conclusion what shall be provided for future and what not?

Often working with various jars and exploring the features specially in corner cases, I often realize and think that how is that they thought that it might be a useful scenario somewhere in future ...