Application Programming Interface (API) Design discusses best practises for creating libraries intended for general purpose or public use.
3
votes
0answers
24 views
Extending ACL with more sophisticated rules in web REST API
I am currently working a REST API design and I am looking for a way to add an advanced ACL management, beyond what
Let's consider for instance that I have a route which is the following :
/profile/...
0
votes
3answers
101 views
How to implement Progressive Disclosure in C++ API
Following the article Programmers Are People Too by Ken Arnold, I have been trying to implement the progressive disclosure pattern for an API.
Basically, the idea mentioned in the text is to break ...
0
votes
1answer
42 views
Why use an intermediate API in this Azure App Service setup?
I was checking out the App Service on Azure and in one of the tutorials two API apps are created, one for data and one to be accessed by external apps.
It's not clear to me from the tutorial what ...
3
votes
1answer
92 views
One function to produce a couple or a function per item?
I have a dilemma. Let's say I have an AST that describes some grammar, for instance. I can write a function to stringify this AST back into human-readable BNF form or generate a parser from it. I can ...
5
votes
1answer
142 views
OpenGL: Why are things bound instead of being passed directly as parameters?
In OpenGL you have to bind an object to the context to be used in subsequent calls, instead of just using it as an argument in those calls.
For example, in OpenGL you write this
glGenBuffers( 1, &...
3
votes
0answers
63 views
API design: stream objects vs. functions vs. messages
I'm designing API for a python library that accepts asynchronous input and produces asynchronous output: various signals come in, and various signals are generated in response (there's no one-to-one ...
5
votes
1answer
68 views
What is a canonical schema in a context of microservices architecture?
A recent question mentioned the term canonical schema in a context of microservices architecture. After reading the Wikipedia article, as well as one of the answers to the question, I still don't ...
4
votes
4answers
151 views
How to prevent data-scanning via public API?
Our customer (a bank) needs to publish a web-service API for use by 3rd party applications. The security is going to involve OAuth2 and JWT (JSON Web Token).
The problem is that the customer is afraid ...
1
vote
1answer
55 views
Collection properties and initializer lists in .Net API design
The following is a quote from Microsoft's framework design guidelines:
Collection Properties and Return Values
X DO NOT provide settable collection properties.
Users can replace the ...
4
votes
2answers
181 views
Is it bad practice to generate ids for an object that does not yet exist in the database?
Here is the situation:
There is a Mongo database A and there is Mongo database B.
There is a business concept/Mongo object that is called someModel which exists on one of database B's collections.
...
4
votes
2answers
97 views
What do you call the layer of modules that call external APIs?
I'm creating a Node app.
I have JavaScript files that include custom functions that make calls to external APIs (in this case Google APIs)
I have JavaScript files in my node app that are related ...
1
vote
3answers
143 views
Restful API design/ structure Decision
I´m currently creating my first restful API for a WebApp and I´m at a point where I´m not sure, how to best structuring it.
Background Information
I´m developing a Holiday planer for a Company. The ...
4
votes
2answers
98 views
Where should HTTP calls resides in a layered architecture?
I have a client which depends on data fetching from two different domains.
Client fetches the data from Domain "A"'s API layer and Domain "A"'s Data Depends on Domain "B"
There is an implementation ...
0
votes
0answers
61 views
JSON APIs in PHP, across the internet
I am building a proof of concept for data processing web service, that allows users to get data cleaned, homogenized or otherwise manipulated.
Often users send different types of data in the same ...
2
votes
2answers
353 views
Should Microservices talk to each other?
I'm designing an application using Micro-Services and I'm unsure on the best mechanism to use to collect data from multiple services.
I believe there are two options:
Integrate an 'inter-service' ...
1
vote
1answer
92 views
Why does C#'s System.Threading.Semaphore implement IDisposable and why doesn't java.util.concurrent.Semaphore implement Closeable?
In .NET framework, System.Threading.Semaphore is a IDisposable that require manually dispose. However, in JavaSE, java.util.concurrent.Semaphore is not a Closeable nor a AutoCloseable.
Why do they ...
0
votes
0answers
21 views
Designing API for length constrained input array
I need to expose an API A which internally uses another API B. API B accepts an array of product codes and returns their information. That array could have any length but API B will return information ...
0
votes
0answers
29 views
Refer to the user in API URL (me, my or self)
Is there a known best practice when referring to the authenticated user in an API URL?
For example, the Facebook API uses /me as a prefix to all the resources of the authenticated user.
But I can ...
0
votes
1answer
41 views
Supporting SOAP Web Services APIs
I am creating a software for B2B which targets all kinds of large size companies. It will integrate with existing softwares of companies (CRM and ERP systems). I want to expose my API via REST. ...
0
votes
1answer
29 views
security in selfhost web api
I am currently sketching out a project I am doing at my job, where I will have a self hosted WebAPI, connected to a serial device, where the app I am creating will configure that device. No, it is not ...
0
votes
1answer
41 views
What is a good REST convention for the structure of a response that is just a container of two (or more) unrelated entities
Let's say I have the following entities that can be accessed at the following URIs (using the standard pluralization):
/things/:id and /otherthings/:id
I want to expose for performance reasons, an ...
2
votes
1answer
31 views
API route design for optional entity relationships
Suppose I have Project and Task entities for a to-do list. If Tasks are required to be in a Project, the Task routes would probably look like this:
GET /projects/{projectId}/tasks returns all ...
1
vote
2answers
40 views
Internal API - Some larger generic methods, or many very specific methods
I'm building a web API that is going to be consumed by several internal systems. Naturally the different systems have different requirements. The consumers may create change requests to the API, when ...
0
votes
2answers
91 views
validation error responses in REST API
I'm designing a RESTful API and wondering what's the best format for validation error messages.
For example, my account creation endpoint accepts a JSON object:
user: {
first_name: string,
...
2
votes
3answers
89 views
Which REST API URI should be used for querying a relation to a single model object?
I am developing a REST API for a user management service (being used by other micro services). My model contains the types User and Server among others. Server to User relation is many-to-one (each ...
1
vote
2answers
91 views
Single Web API endpoint for all entities, good or bad?
Situation
We are currently developing a large web application (Web API 2) - several entities and thus require several endpoints for each. But suddenly, they changed to "one endpoint fits all" ...
1
vote
1answer
51 views
RESTful nested resources
I have a profile resource. Profiles can have a parent and an arbitrary number of child profiles.
What's the best way to model this in a RESTful scenario?
I thought of a number of different solutions,...
0
votes
2answers
117 views
Is the SOLID principles applicable to API:s
I have built an (web) API with a couple of endpoints, which in turn have a lot of CRUD-operations. The code itself conforms to the SOLID principles. Now I have a consumer for that API which states ...
3
votes
2answers
254 views
What public interface should I offer for creating objects that know about each other?
I'm creating a library in C# which will be used to query databases.
In order to use this library, a user first needs to tell the library what the database schema contains, by creating Schema, Table, ...
1
vote
1answer
138 views
What architecture should I use to create an “events” application in .NET?
I'm fairly new to C# and .NET as a whole and I want to create an application, I have strong experience in Java, Hibernate and using MVC frameworks like Spring.
I want to create an application that ...
17
votes
5answers
4k views
Function returning true/false vs. void when succeeding and throwing an exception when failing
I'm building an API, a function that uploads a file. This function will return nothing/void if the file was uploaded correctly and throws an exception when there was some problem.
Why an exception ...
1
vote
2answers
185 views
Why is it CRUD instead of GRAS? [closed]
Why is it
Create
Read
Update
Delete
instead of
Get
Remove
Add
Set
?
I've been working with an API that uses ADD and SET and REMOVE. Most accessor functions are named get...() and set...(). I ...
1
vote
1answer
41 views
In which order should page- and pageSize-parameters be used?
I'm building an api and a bit into the development I realized that I constantly change the order of the page and pageSize parameters.
Currently I use C# and javascript, so the method declaration ...
5
votes
2answers
122 views
Good practice for status code returned by restfull API when validating a token
I am working on client JavaScript SPA and a restful API on HTTPS.
Client application needs to call a public endpoint (no token required) in order to valid (GET) a specific TOKEN previously remember ...
0
votes
1answer
80 views
External Reasons an API call might fail?
I'm currently in the process of developing my first API. This is a private api that will send information back and forth between my two sites, not one that will be open to the public. I'm working on ...
0
votes
0answers
32 views
Web, REST, SOAP, etc., API dependency discovery
I am not sure what the correct terminology is as I have not seen this topic discussed in any articles. Often to call an API one must find the number of parameters from another API/service etc. My ...
1
vote
1answer
126 views
Securing a private API
I have two sites and an API that sends data back and forth between the two. The API is only used on the back end, and the user will not interact with it at all. What I would like to do is ensure that ...
0
votes
1answer
41 views
API design: POST with query parameter for specifying relationship?
Say I have a User resource which must always be attached to another type of resource, a Business.
When creating a new User, is it OK to have the POST endpoint use a query parameter to specify the ...
0
votes
0answers
75 views
URL API design considerations and REST action
We have a cart and cart has line items, now line items can be products, discount coupons, rewards and promotions. I am looking for some inputs in design consideration here. The backend is in Ruby on ...
4
votes
1answer
89 views
Does InternalsVisibleToAttribute indicate a bad design smell?
Every time I have used the InternalsVisibleToAttribute when developing an API, it feels a bit smelly. Like the API is not being designed in a truly encapsulated way. A lot of the times this is out of ...
1
vote
2answers
67 views
Complex query for resource
Say I'm offering a REST'ish API that offers you Meals
Now If you want to get ALL meals naturally you get it through something like:
GET /meals
if you want to filter those meals you can do something ...
1
vote
3answers
105 views
Is it bad practice to have client application dynamically determine the rate limit for your API?
I stumbled across an API from a popular vendor in my sector that asks the client to dynamically determine the max records allowed in a single POST request by first performing a GET request and ...
14
votes
3answers
556 views
Should I return an HTTP 400 (Bad Request) status if a parameter is syntactically correct, but violates a business rule?
Say that I have a REST endpoint that takes an integer as a parameter:
/makeWaffles?numberOfWaffles=3
In this case, I want the number to be positive because I can't make a negative number of waffles (...
1
vote
2answers
79 views
Is reusing an API across wildly different targets a good practice?
Let's say I have something called "Actuators". Each "Actuator" may have capabilities associated with it. Should I reuse it wherever it fits, or should I create entirely separate kinds of actuators for ...
0
votes
1answer
61 views
RESTful way to define an API that requires two keys to return a resource
In my application, I have resource A that is super class and A1, A2 that inherits A and other properties that are specific to them. A cannot exist by itself, it must be either A1 or A2. This is a ...
0
votes
1answer
104 views
Analytics Architecture for Multiple APIs
We’re building a platform of different APIs (every API is written by different team, different timezone).
We want to implement unified analytics for all of the APIs to have one data lake as a single ...
0
votes
1answer
147 views
REST API: Handle “partial” nested objects
Let's say we have schools with some data including a name and a list of students, and students with some data including courses they're enrolled in and a reference to their school. On the client:
I'd ...
1
vote
0answers
40 views
Would it be a good idea to use variadic functions in a C API as a means of preserving the ABI?
Say you're designing a C API, and one of your big concerns is ABI stability (it's going to be deployed as a shared library, or whatever).
You have a function exported
int foo_bar(int a, int b, int*...
0
votes
2answers
124 views
How to tie the request filters to the data model in a REST API
I am trying to build a RESTful search api (POST request) that can return different types of resources (e.g A, B, C, etc). I have defined a data model for each of the resource type. There are some ...
1
vote
0answers
67 views
RestAPI design for exposing RabbitMQ
I'm creating an API to publish and consume message from RabbitMQ. In my current design, the publisher is going to make a POST request. My API will route the POST request to the exchange. In this way, ...
