Software Engineering Stack Exchange
Software Engineering Stack Exchange

Questions tagged [api-design]

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

Good APIs are easy to use, require less explanation, are not slow and integrate well with the languages and environments they were intended for. They are also forgiving of caller errors and report accurate, descriptive errors.

1134 questions
38
votes
6 answers

Is there a pattern for handling conflicting function parameters?

We have an API function that breaks down a total amount into monthly amounts based on given start and end dates. // JavaScript function convertToMonths(timePeriod) { // ... returns the given time period converted to months } function…
CalMlynarczyk
  • 491
15
votes
6 answers

What do great APIs have in common?

What is it about great APIs that makes them great? I think that adhering to the "do one thing and do it well" mantra is a good sign and being is a good mapping to the problem domain is important, but what do great APIs have in common?
dan_waterworth
  • 7,297
9
votes
2 answers

How to decide if an API should be synchronous or asynchronous?

I am developing a service which will expose some APIs through REST end-point. I have some API which can take a lot of time like say 5 to 10 minutes to complete the requested operation. I am also writing the client side application which is…
ryen
  • 155
9
votes
1 answer

Sending a collection of data to an API. Multiple small calls vs one big call

I am currently creating an API and implemented a few basic REST actions such as get, update, search etc. Another program that collects data needs to synchronize these to this API. My current thought is: What would be good practice to synchronize…
pdu
  • 579
7
votes
5 answers

How to represent business logic in restful API

Let's imagine that I have an employee resource. { "id": 1, "name": "John", "role": "Office manager" } And I want an endpoint that promotes them. As part of that I want some side effects to happen, such as an email goes to HR. How should I…
GMon
  • 191
7
votes
2 answers

As an API-user, would you tolerate BestPractice Exceptions?

I'm in the process of designing an API, part of which involves writing POCOs to a database. In C#, we have the DateTime structure. The "default" value for this (DateTime.MinValue) is 01/01/0001. Part of the API serializes POCOs to the database. If…
Moo-Juice
  • 1,378
6
votes
1 answer

Why should I map external IDs to internal IDs in my API?

We have a public API. Users will call this API by passing in different Guids as the IDs for entities. In the API, the Guid will be translated to the internal ID (Int32) for that particular record in our DB. The public API calls our internal API and…
David Klempfner
  • 309
5
votes
2 answers

Coarse-grained views on server vs fine-grained views assembled on client vs fine-grained views with batching

I've currently got a browser talking via an "API" to the server. API is scare quoted because the API really wouldn't support another user interface very well, because it consists of every call our UI happens to need, in the form it happens to need…
psr
  • 12,866
  • 5
  • 39
  • 67
4
votes
3 answers

Implementing Heartbeat using REST API

I have a server which is exposing API through REST. I need to implement a simple Heartbeat service to monitor this server status and availability of API. The interval of Heartbeat check will be every few seconds, like every 3 seconds. Is it good…
ryen
  • 155
3
votes
1 answer

API Design: How to Specify an Arbitrary Tree?

I'm writing an API, in which one of the function calls of which is meant to be a call to a factory for a series of tree nodes that take a number of parameters, some of which are the same and some of which are different. The kicker is that it's on…
Sebastian Lenartowicz
  • 361
3
votes
2 answers

Hit the Upper Limit for Cross Platform API Capabilities

I am a junior programmer who works as an intern(8 mths into the internship) in a team of 1(myself only) creating mobile phone apps & websites. I have created an App that works exactly how it should & has some pretty cool features but the App fails…
Mack
  • 31
2
votes
1 answer

Should an API resource have multiple endpoints?

Should a resource be available through more than one URL endpoint? For instance, I have exam resources which contain multiple question resources which in turn contain multiple answer resources. The endpoints to list questions and view a single…
mcon
  • 131
2
votes
3 answers

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 implementation changes?
user3339411
  • 449
  • 4
  • 7
2
votes
5 answers

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=2015-05-31 which returns an array of all login dates of…
Alex
  • 121
2
votes
1 answer

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 applications each of which have a unique API key.…
Liath
  • 3,426
  • 1
  • 21
  • 33
1
2 3