Application Programming Interface (API) Design discusses best practises for creating libraries intended for general purpose or public use.
3
votes
2answers
88 views
What should I think of when making an internal API public?
An internal API I've built will soon be consumed by a third party.
Should I open the current internal API to the public, or should I create a new API endpoints for external access?
0
votes
1answer
28 views
Creating a better translation for a node.js api to ruby
My client has a nodejs SDK that fetches entries using a client that makes http requests. Their api looks like this:
var Query = Client.ContentType('blog').Query();
Query
.where("title", ...
6
votes
1answer
171 views
RESTful API and i18n: how to design the response?
We are designing a RESTful API that is mainly intended to meet the needs of a single client. Because of its very particular circumstances, this client has to make as few requests as possible.
The ...
1
vote
2answers
58 views
Conflict in getter and setter method names in ruby api design
I am inheriting an api decision in an SDK I am writing where I am required to fetch domain objects (entries) from the server like this:
blogEntries = client.content_type('blog').entries
As you can ...
0
votes
2answers
94 views
RESTful API design for an existing domain implementation of a simple game?
I'm trying to wrap a RESTful API around an existing implementation of a game.
Here is a possible state diagram of a simple API design that comes to mind:
I'm having troubles here because the ...
1
vote
3answers
61 views
Should API version change when data is added?
Title says it all. Should I increment my API version if I add, say, an image property to each instance of my JSON-represented 'Restaurant' resource? or should API versioning change only when ...
3
votes
2answers
117 views
Is it legal for a RESTful API to provide different structures for a given resource? How should that be modeled?
I'm using swagger to prototype a RESTful API and I got to a situation where one property is part of a resource but not always should be filled.
Let's say my resource is stores.
Basic endpoints would ...
3
votes
1answer
83 views
API versioning, where to point unversioned API
I always see the discussion when there's an API version in the URL where to point the versionless one.
I mean look at these three URLs.
http://host/api/customers/1
http://host/v1/api/customers/1
...
3
votes
1answer
202 views
RESTful api and nested resources
Having built a RESTful API (using Laravel) for a project at work, I followed what seemed (from lots of reading) to be a the majority in terms of my approach to nested resources - by defining them in ...
0
votes
1answer
38 views
How to create access control on a record level on derived entities?
I have a data model based around users. User owns records on several derived entities, e.g. A user have tasks and each task have documents. Documents don't have the User ID in their properties, only ...
1
vote
5answers
147 views
Define a RESTful API for creating/updating other resource definitions?
Let's say I have a users resource, with two properties: name and email as specified by a users JSON Schema document, which right now looks like this:
{
"$schema": "http://json-schema.org/draft-04/...
4
votes
0answers
54 views
GraphQL - Should I expose link tables?
I am experimenting with converting an API to GraphQL, and I have a database that has many-to-many relationships that are stored via link tables; something like this:
CREATE TABLE accounts
(
id int,
...
5
votes
5answers
792 views
How does a REST API fit for a command/action based domain?
In this article the author claims that
Sometimes, it is required to expose an operation in the API that inherently is non RESTful.
and that
If an API has too many actions, then that’s an ...
0
votes
0answers
45 views
Building a set of APIs on top of a legacy application that can also write into the source database?
OK, so please tell me if this is the worst idea ever, or if it might have some merit. Here it goes:
I have a customer who uses a legacy application that stores data in an Omnis database file (*.DF1)....
0
votes
0answers
26 views
Oauth2 REST API: for 3rd party and internal
I have Oauth2 REST API. There are 3rd party applications (server (like web app) and client (like mobile app)). We want to add some functionality to this API which could be used only by our official ...
0
votes
0answers
48 views
Has Anyone Included Consuming WADL in .Net Yet?
Most answers I see online are "You don't need a contract to consume RESTful services". But currently, consuming endpoints is one of the biggest time commitment issues in our .NET environment. Oh how ...
2
votes
2answers
102 views
REST API update child reference
I'm working on a project where we are creating some REST APIs
My question is when we are creating an API to update an entity that contains a children reference, i.e.
{
name: '...',
email: '.....
1
vote
0answers
95 views
Should third-party types be exposed in a public API?
tl;dr: Should I avoid exposing third-party types in a public interface?
I'm working on a Kotlin-based project that relies heavily on data keyed with two values. It's just something I'm tinkering ...
0
votes
0answers
30 views
Keep data up to date via api
I have a program that needs to get a part of its data from an api of another program, and the data needs to update every 5 seconds.
For example:
I have a program that presents homework for each ...
4
votes
1answer
62 views
Suggested method for “simplifying” EAV
I am working on a GIS platform that basically handles roads with features. The system uses an EAV model to store all the data in a database. The system has been around for a while and there is nothing ...
3
votes
0answers
37 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
4answers
156 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
46 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
98 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
154 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
69 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
119 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
170 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
74 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
189 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.
...
6
votes
2answers
135 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
149 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
106 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 ...
1
vote
0answers
66 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
744 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
102 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
22 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
30 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
43 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
49 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
54 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
34 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
41 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
221 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
122 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
101 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
69 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
134 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
267 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
159 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 ...
