10 ms·

An Introduction to APIs

244 points by teleforce 3y ago

lolive 3y ago
I think JSON [tree] data [with no fixed field for unique identifier, and no fkey referencing] is wrong. The lack of a proper type system+schema for data is wrong. The need for server-side query management makes any API supremely rigid. Still some concerns to solve, for me, with REST APIs.
- JimDabell 3y ago
  JSON covers syntax not semantics. This means you can build the formats you want on top of JSON by only describing the semantics without having to make decisions about syntax or write parsers.
  - lolive 3y ago
    Not taking care of the semantics and letting [mostly] code take care of it is what I don’t like about that format. [standardization of @id and @type special attributes by JSON-LD sound like a good step forward, imho]
    - JimDabell 3y ago
      My point is that there’s no point in complaining that a JSON API doesn’t have any particular semantics like the ones you want. If an API says that the format it returns is “JSON”, then what it actually means is that it’s some ad hoc format cooked up on the spot that uses JSON syntax. The problem is not that JSON doesn’t include semantics – that’s out of scope for JSON – the problem is that the API in question half-assed its format design. > standardization of @id and @type special attributes by JSON-LD sound like a good step forward But those were standardised. In the JSON-LD spec. If you want a format that has specified semantics, use a format that has specified semantics. Like JSON-LD. JSON only solves the syntax part of the problem, by design. It’s not there to define semantics, that’s what formats built on top of JSON do.
aggrrrh 3y ago
Basic REST and JSON RPC are very simple to start with, but have common problems when application gets bigger. How do you represent relations, pagination, filtering etc? My go-to specification for structuring JSON documents is https://jsonapi.org/ https://jsonapi.org/ It covers most basic needs of a standard API.
eska 3y ago
People are complimenting great technical writing here, but the first definition they provide is this: > Technically, an API is just a set of rules (interface) that the two sides agree to follow. The company publishing the API then implements their side by writing a program and putting it on a server. In practice, lumping the interface in with the implementation is an easier way to think about it. which is neither technically correct, nor easy to understand for a layperson. Compare to Wikipedia: > An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software.
xtiansimon 3y ago
Ch6 “Linking resources together” This is the most difficult topic for me. I struggle to discover, understand and implement in my code highly linked resources. How an API is organized or designed should be its own chapter IMHO “We'll skip the details… […] REST practitioners are split on how to solve the problem of associating resources.” UUUG
distantsounds 3y ago
(2014)
delta_p_delta_x 3y ago
Web dev has so thoroughly revised the definition of 'API' it's not even funny. Desktop, embedded, video games, HPC suddenly cried out in terror and were suddenly silenced.
- 3cats-in-a-coat 3y ago
  It's become just a word that means "interface endpoints". And frankly that's fine, it's what it is in the end. Whether in an OS, a website, or another platform.
- rewmie 3y ago
  > Web dev has so thoroughly revised the definition of 'API' it's not even funny. What leads you to believe that a HTTP API does not meet the definition of a API?
  - debugnik 3y ago
    The other way around, the meaning of API standalone has been narrowed to mean HTTP APIs, as if it were redundant. Specially tedious if you're searching for non-HTTP API design notes.
    - rewmie 3y ago
      > The other way around, the meaning of API standalone has been narrowed to mean HTTP APIs (...) I don't think so. The pervasiveness of web apps and applications consuming web services means there's a lot of work involving web APIs. This doesn't mean the definition of API was narrowed. It's all about context. If your bread and butter is developing web services, you don't waste time with context-free definitions of your API. You talk about the API and everyone is on the same page.
      - evandale 3y ago
        If all anyone ever talks about is APIs in the web services sense then, yes, the definition of API has been narrowed. When everyone will assume you mean web services API when you refer to an API and have to use extra words to describe non-web APIs then the definition has narrowed. That's how English works: the definitions of words depend on their usage and dictionaries describe how words are used. You even admitted "The pervasiveness of web apps and applications consuming web services means there's a lot of work involving web APIs" and "If your bread and butter is developing web services, you don't waste time with context-free definitions of your API" which is acknowledging the common use definition of API has morphed into Web API. It's only in the context of technical documents or documents that are explicitly referring to non-web APIs that use API and it is understood to mean something other than a web API.
synergy20 3y ago
maybe call it 'cloud APIs' It was written in 2014, not sure if it's still 'up to date' but the articles seem well written, concise, to the point.
aridiculous 3y ago
There’s nothing like good technical writing.
sibit 3y ago
> POST - Asks the server to create a new resource > PUT - Asks the server to edit/update an existing resource Maybe I've been doing it wrong all these years but it seems to me that the guides flip-flops the responsibility of POST and PUT. My understanding is that POST should edit/modify while PUT creates/replaces a resource.
- hairofadog 3y ago
  I’ve always known it as stated in the article, and I’m pretty sure that’s right, though I’ve never noticed any functional difference between the two (aside from what any given API may enforce).
- nighthawk454 3y ago
  I thought the same, but apparently the article is correct https://www.ietf.org/rfc/rfc2616.txt https://www.ietf.org/rfc/rfc2616.txt
  - sibit 3y ago
    Interesting. I guess I've been going off of RFC 7231 > The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. https://www.ietf.org/rfc/rfc7231.txt https://www.ietf.org/rfc/rfc7231.txt
    - blowski 3y ago
      My rule of thumb: if you know the ID of the resource you’re creating, it’s a PUT. If the system generates the ID, then it’s a POST.
      - treve 3y ago
        More generally the URI instead of the ID.
        3y ago
ChrisArchitect 3y ago
(2014)
danjc 3y ago
Side point - has anyone got a better way to refer to a non-technical person than "non-technical"? I see they use that term in the intro and I use it to but seems a bit condescending.
- vorpalhex 3y ago
  When an accurate term seems condescending, sometimes that tells us more about ourselves than the word.
- deleted 3y ago
  [deleted]
- pranavpiyush 3y ago
  Business user
- FractalHQ 3y ago
  Muggle
- mellosouls 3y ago
  Layperson (layman in old money), though I don't think non-technical is normally condescending. https://dictionary.cambridge.org/dictionary/english/layperson https://dictionary.cambridge.org/dictionary/english/layperso... someone who is not an expert in or does not have a detailed knowledge of a particular subject "bluffer" would be a humorous alternative.
- gabereiser 3y ago
  The phrase you seek is called “Layman’s Terms” as defined: https://www.merriam-webster.com/dictionary/layman%27s%20terms https://www.merriam-webster.com/dictionary/layman%27s%20term... This avoids classification of the reader. To refer to someone who lacks the knowledge of a domain, they are a “layman”.
- ch1234 3y ago
  …. And that’s the entire world is in this state. Stop trying to create victims out of people for no reason. Non-technical = not technical = does not have technical expertise. Seems pretty logical to me
dinoreic 3y ago
REST is for noobs, JSON RPC is silent pro's choice :) Make all requests POST and enjoy easy life without useless debates on should creation of resource be on POST or PUT or should you return HTTP status 404 or 200 if resource/document on server is not found (of course if should be 200 because request was a success, 404 should only be used it api method is not found). I 100% agree with Troy Griffitts beautiful take https://vmrcre.org/web/scribe/home/-/blogs/why-rest-sucks https://vmrcre.org/web/scribe/home/-/blogs/why-rest-sucks
- eikenberry 3y ago
  +1 and I'll bump it up a notch... not only should you ignore REST you should ignore URLs. You want to write protocols, not APIs. Redis, for example, has a better "API" than any web API I've used. Easy to use, easy to wrap, easy to extend and version. HTTP is the other obvious example that I shouldn't have to go into. If you'd like a good back and forth on the idea the classic c2 page is a great resource. http://wiki.c2.com/?ApiVsProtocol http://wiki.c2.com/?ApiVsProtocol
  - nine_k 3y ago
    Don't ignore URLs completely! They are great for namespacing and versioning.
    - eikenberry 3y ago
      Why add the additional complexity of multiple connection points? Protocols support both of those operations perfectly well and it seems that adding URLs would just confuse things.
      - liquidgecka 3y ago
        Because at some point you will need to deprecate ciphers and when you do you don't want old clients to explode. The domain is the way you version connection requirements so you can support old clients with crappy ssl options without screwing up the security of new clients.
foundart 3y ago
Very well written. However, I have never thought of the word 'endpoint' as used in API documentation in the way they describe it. I have no idea what the true origin is but I've always thought of it as the end of the journey the api request makes over the network. > These are called endpoints simply because they go at the end of the URL, as in http://example.com/<endpoint_goes_here> http://example.com/<endpoint_goes_here>.
deleted 3y ago
[deleted]
gumby 3y ago
Title should say "Web APIs".
- defanor 3y ago
  As should the contents.
shortrounddev2 3y ago
I still like REST. Most web applications are CRUD and don't need RPC. It also provides a standard and expected interface for 3rd party developers integrating with your code. If you're a small saas startup, nobody is going to waste their time learning the particularities of your protocol. Also makes the code very easy to read if you follow best practices for MVC style webapis with dependency injection. In my view, asp.net core is the apex of all RESTful frameworks
- irishloop 3y ago
  Precisely right. Standards work cause everyone understands them. I know a PUT request is almost certainly an update of some kind. I know a POST makes something. For most shit you wanna do, its view, edit, delete, its really not that complicated.
  - jmondi 3y ago
    Am I the only one around here who hates the whole PUT PATCH nonsense? When I write APIs, you’re either querying data with a GET, or mutating data with a POST. Everything else is a waste of time.
    - tacker2000 3y ago
      Yea, I also frigging hate it. Everytime i need to plan out an API i stumble into a lengthy PUT/PATCH analysis and read up session that shouldnt really be necessary. POST should be the only thing needed, if the object already exists, mutate it, if not, create it, in 99% of the times you dont need the “idempotency” argument.
    - kiitos 3y ago
      This suggests you just don't grok HTTP semantics.
      - jmondi 3y ago
        No no, this just means I think the HTTP semantics are overkill, and a simple GET/POST gets across everything that I need to.
seveibar 3y ago
This article advocates for a traditional REST API design. At Seam, we use an API design that is like a RESTful RPC API, inspired by the API at Slack. I think that HTTP RPC and Slack-like APIs are much better than traditional REST because most consumers of an API use an SDK, and RPC-style HTTP APIs optimize for the SDK usage. We also built a framework like trpc but for Next REST APIs[1] to get all the nice benefits of shared types but also the nice benefits of OpenAPI generation that typically come with RESTful frameworks https://github.com/seamapi/nextlove https://github.com/seamapi/nextlove
ninja-ninja 3y ago
was talking to someone about how product managers should have an understanding of engineering and they said you should just know what apis are haha

244 points by teleforce 3y ago

I think JSON [tree] data [with no fixed field for unique identifier, and no fkey referencing] is wrong. The lack of a proper type system+schema for data is wrong. The need for server-side query management makes any API supremely rigid. Still some concerns to solve, for me, with REST APIs.

JimDabell 3y ago
JSON covers syntax not semantics. This means you can build the formats you want on top of JSON by only describing the semantics without having to make decisions about syntax or write parsers.
- lolive 3y ago
  Not taking care of the semantics and letting [mostly] code take care of it is what I don’t like about that format. [standardization of @id and @type special attributes by JSON-LD sound like a good step forward, imho]
  - JimDabell 3y ago
    My point is that there’s no point in complaining that a JSON API doesn’t have any particular semantics like the ones you want. If an API says that the format it returns is “JSON”, then what it actually means is that it’s some ad hoc format cooked up on the spot that uses JSON syntax. The problem is not that JSON doesn’t include semantics – that’s out of scope for JSON – the problem is that the API in question half-assed its format design. > standardization of @id and @type special attributes by JSON-LD sound like a good step forward But those were standardised. In the JSON-LD spec. If you want a format that has specified semantics, use a format that has specified semantics. Like JSON-LD. JSON only solves the syntax part of the problem, by design. It’s not there to define semantics, that’s what formats built on top of JSON do.

aggrrrh 3y ago

Basic REST and JSON RPC are very simple to start with, but have common problems when application gets bigger. How do you represent relations, pagination, filtering etc? My go-to specification for structuring JSON documents is https://jsonapi.org/ https://jsonapi.org/ It covers most basic needs of a standard API.

eska 3y ago

People are complimenting great technical writing here, but the first definition they provide is this: > Technically, an API is just a set of rules (interface) that the two sides agree to follow. The company publishing the API then implements their side by writing a program and putting it on a server. In practice, lumping the interface in with the implementation is an easier way to think about it. which is neither technically correct, nor easy to understand for a layperson. Compare to Wikipedia: > An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software.

xtiansimon 3y ago

Ch6 “Linking resources together” This is the most difficult topic for me. I struggle to discover, understand and implement in my code highly linked resources. How an API is organized or designed should be its own chapter IMHO “We'll skip the details… […] REST practitioners are split on how to solve the problem of associating resources.” UUUG

distantsounds 3y ago

(2014)

delta_p_delta_x 3y ago

Web dev has so thoroughly revised the definition of 'API' it's not even funny. Desktop, embedded, video games, HPC suddenly cried out in terror and were suddenly silenced.

3cats-in-a-coat 3y ago
It's become just a word that means "interface endpoints". And frankly that's fine, it's what it is in the end. Whether in an OS, a website, or another platform.
rewmie 3y ago
> Web dev has so thoroughly revised the definition of 'API' it's not even funny. What leads you to believe that a HTTP API does not meet the definition of a API?
- debugnik 3y ago
  The other way around, the meaning of API standalone has been narrowed to mean HTTP APIs, as if it were redundant. Specially tedious if you're searching for non-HTTP API design notes.
  - rewmie 3y ago
    > The other way around, the meaning of API standalone has been narrowed to mean HTTP APIs (...) I don't think so. The pervasiveness of web apps and applications consuming web services means there's a lot of work involving web APIs. This doesn't mean the definition of API was narrowed. It's all about context. If your bread and butter is developing web services, you don't waste time with context-free definitions of your API. You talk about the API and everyone is on the same page.
    - evandale 3y ago
      If all anyone ever talks about is APIs in the web services sense then, yes, the definition of API has been narrowed. When everyone will assume you mean web services API when you refer to an API and have to use extra words to describe non-web APIs then the definition has narrowed. That's how English works: the definitions of words depend on their usage and dictionaries describe how words are used. You even admitted "The pervasiveness of web apps and applications consuming web services means there's a lot of work involving web APIs" and "If your bread and butter is developing web services, you don't waste time with context-free definitions of your API" which is acknowledging the common use definition of API has morphed into Web API. It's only in the context of technical documents or documents that are explicitly referring to non-web APIs that use API and it is understood to mean something other than a web API.

synergy20 3y ago

maybe call it 'cloud APIs' It was written in 2014, not sure if it's still 'up to date' but the articles seem well written, concise, to the point.

aridiculous 3y ago

There’s nothing like good technical writing.

sibit 3y ago

> POST - Asks the server to create a new resource > PUT - Asks the server to edit/update an existing resource Maybe I've been doing it wrong all these years but it seems to me that the guides flip-flops the responsibility of POST and PUT. My understanding is that POST should edit/modify while PUT creates/replaces a resource.

hairofadog 3y ago
I’ve always known it as stated in the article, and I’m pretty sure that’s right, though I’ve never noticed any functional difference between the two (aside from what any given API may enforce).
nighthawk454 3y ago
I thought the same, but apparently the article is correct https://www.ietf.org/rfc/rfc2616.txt https://www.ietf.org/rfc/rfc2616.txt
- sibit 3y ago
  Interesting. I guess I've been going off of RFC 7231 > The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. https://www.ietf.org/rfc/rfc7231.txt https://www.ietf.org/rfc/rfc7231.txt
  - blowski 3y ago
    My rule of thumb: if you know the ID of the resource you’re creating, it’s a PUT. If the system generates the ID, then it’s a POST.
    - treve 3y ago
      More generally the URI instead of the ID.
      - 3y ago

ChrisArchitect 3y ago

(2014)

danjc 3y ago

Side point - has anyone got a better way to refer to a non-technical person than "non-technical"? I see they use that term in the intro and I use it to but seems a bit condescending.

vorpalhex 3y ago
When an accurate term seems condescending, sometimes that tells us more about ourselves than the word.
deleted 3y ago
[deleted]
pranavpiyush 3y ago
Business user
FractalHQ 3y ago
Muggle
mellosouls 3y ago
Layperson (layman in old money), though I don't think non-technical is normally condescending. https://dictionary.cambridge.org/dictionary/english/layperson https://dictionary.cambridge.org/dictionary/english/layperso... someone who is not an expert in or does not have a detailed knowledge of a particular subject "bluffer" would be a humorous alternative.
gabereiser 3y ago
The phrase you seek is called “Layman’s Terms” as defined: https://www.merriam-webster.com/dictionary/layman%27s%20terms https://www.merriam-webster.com/dictionary/layman%27s%20term... This avoids classification of the reader. To refer to someone who lacks the knowledge of a domain, they are a “layman”.
ch1234 3y ago
…. And that’s the entire world is in this state. Stop trying to create victims out of people for no reason. Non-technical = not technical = does not have technical expertise. Seems pretty logical to me

dinoreic 3y ago

REST is for noobs, JSON RPC is silent pro's choice :) Make all requests POST and enjoy easy life without useless debates on should creation of resource be on POST or PUT or should you return HTTP status 404 or 200 if resource/document on server is not found (of course if should be 200 because request was a success, 404 should only be used it api method is not found). I 100% agree with Troy Griffitts beautiful take https://vmrcre.org/web/scribe/home/-/blogs/why-rest-sucks https://vmrcre.org/web/scribe/home/-/blogs/why-rest-sucks

eikenberry 3y ago
+1 and I'll bump it up a notch... not only should you ignore REST you should ignore URLs. You want to write protocols, not APIs. Redis, for example, has a better "API" than any web API I've used. Easy to use, easy to wrap, easy to extend and version. HTTP is the other obvious example that I shouldn't have to go into. If you'd like a good back and forth on the idea the classic c2 page is a great resource. http://wiki.c2.com/?ApiVsProtocol http://wiki.c2.com/?ApiVsProtocol
- nine_k 3y ago
  Don't ignore URLs completely! They are great for namespacing and versioning.
  - eikenberry 3y ago
    Why add the additional complexity of multiple connection points? Protocols support both of those operations perfectly well and it seems that adding URLs would just confuse things.
    - liquidgecka 3y ago
      Because at some point you will need to deprecate ciphers and when you do you don't want old clients to explode. The domain is the way you version connection requirements so you can support old clients with crappy ssl options without screwing up the security of new clients.

foundart 3y ago

Very well written. However, I have never thought of the word 'endpoint' as used in API documentation in the way they describe it. I have no idea what the true origin is but I've always thought of it as the end of the journey the api request makes over the network. > These are called endpoints simply because they go at the end of the URL, as in http://example.com/<endpoint_goes_here> http://example.com/<endpoint_goes_here>.

deleted 3y ago

[deleted]

gumby 3y ago

Title should say "Web APIs".

defanor 3y ago
As should the contents.

shortrounddev2 3y ago

I still like REST. Most web applications are CRUD and don't need RPC. It also provides a standard and expected interface for 3rd party developers integrating with your code. If you're a small saas startup, nobody is going to waste their time learning the particularities of your protocol. Also makes the code very easy to read if you follow best practices for MVC style webapis with dependency injection. In my view, asp.net core is the apex of all RESTful frameworks

irishloop 3y ago
Precisely right. Standards work cause everyone understands them. I know a PUT request is almost certainly an update of some kind. I know a POST makes something. For most shit you wanna do, its view, edit, delete, its really not that complicated.
- jmondi 3y ago
  Am I the only one around here who hates the whole PUT PATCH nonsense? When I write APIs, you’re either querying data with a GET, or mutating data with a POST. Everything else is a waste of time.
  - tacker2000 3y ago
    Yea, I also frigging hate it. Everytime i need to plan out an API i stumble into a lengthy PUT/PATCH analysis and read up session that shouldnt really be necessary. POST should be the only thing needed, if the object already exists, mutate it, if not, create it, in 99% of the times you dont need the “idempotency” argument.
  - kiitos 3y ago
    This suggests you just don't grok HTTP semantics.
    - jmondi 3y ago
      No no, this just means I think the HTTP semantics are overkill, and a simple GET/POST gets across everything that I need to.

seveibar 3y ago

This article advocates for a traditional REST API design. At Seam, we use an API design that is like a RESTful RPC API, inspired by the API at Slack. I think that HTTP RPC and Slack-like APIs are much better than traditional REST because most consumers of an API use an SDK, and RPC-style HTTP APIs optimize for the SDK usage. We also built a framework like trpc but for Next REST APIs[1] to get all the nice benefits of shared types but also the nice benefits of OpenAPI generation that typically come with RESTful frameworks https://github.com/seamapi/nextlove https://github.com/seamapi/nextlove

ninja-ninja 3y ago

was talking to someone about how product managers should have an understanding of engineering and they said you should just know what apis are haha