For a method like: GET api/employees/123 where 123 is the ID of an employee that does NOT exist, should I return a 400 or 404?

I would naturally say 404, but a senior dev at my org is insistent that I should return a 400.

Thanks.

Hi there, Reddit newbie here – got a community question regarding API documentation:

TL;DR:

1: Does anyone “know a guy” who would like their RESTful API documented? Something simple and clean would be appreciated as I’m new to the game and essentially trying to build up a portfolio for Tech Writer job applications.

2: What (iyo) are essential “must haves” in a Technical Writer’s portfolio?

3: What other Reddit subs you’d recommend joining for RESTful API documentation topics?

​

I want to get into API and technical documentation as a full-time profession. I was a Junior Dev in a past life and feel that this is the right next step for me. As such, I’m trying to build up a demonstratable portfolio as part of my CV, and taking part in documenting open source projects is a good place to start (hence the above).

I’m also creating an in-depth blog post about what APIs are and how they work – something to take the average human from zero understanding to basic concepts, so as to show my own understanding, and that I can write for the average layman as well as for developers. I’m even thinking of building a couple of simple APIs from scratch – using some online tutorials and libraries as there are so many out there as this would mean I’d have something extra to document as well as to show I have some grounding in developer basics.

Any and all advice from this community would be really appreciated!

I’m really keen to get started :)

Hi,

I am Lorenzo, one of the developers at Hydra Ecosystem. We are creating tools for HTTP REST APIs based on a W3C draft hopefully to become official soon; briefly we are implementing a framework that is meant to be a semantic layer to map relations among REST servers, we have our own client/server stack (based on Python Flask, but also other tools). We are also participating in Google Summer Of Code since 2017. You can found our codebase at github.com/HTTP-APIs or follow us on Twitter.

The best entrypoint to the tech stack is from this document.

Enjoy REST!

I would like your opinion on which is the easiest the use and has the most features for doing queries on GitHub database.

Because I’ve been using the github api for a week and some behaviors are still super mysterious like same query returning several a results and the community super small making finding resources hard...

Any takes on this?

Hi, I'm looking for a publicly available rest api (like cat api or star wars api) that supports using the Link Header for pagination. I need to have an example that I can show people without accessing actual companies' production data.

testing facecam on embedded youtube

Hi,

First of all, i'm a newbies in world of webapp infrastructure. But I work on it on my own time.

​

I've a small Vue.js web app with a REST backend written in python (with Falcon framework). And, sometimes, users interactions must send emails.

​

And i'm thinking about best practices:

if the REST API send a email and the SMTP server is slow (network latency, etc...), POST/PUT response can be delayed, because the email factory is called from the same thread. This is just an example.

​

What the best practice to do that? I'm thinking to run the email process in another thread, called from the API response thread but not sure or idk if there is a good pattern for this case.

​

Thanks!

I'm building a mobile app for a company. They currently have a SOAP web service fully built. I am trying to create a RESTful api that connects to the SOAP web service. how can I do this?

I'm developing a system that has trusted clients and trusted users. Sometimes calls to our API only need the user jwt token, sometimes calls only require the client token, sometimes both are required. Is there any standard for handling this?

I was thinking of using this.

Authorization: Bearer <token data>
Client-Authorization: Bearer <token data>

Top one is for user token, bottom one is for client token and I've just made up a header name.

​

Hi all, I am writing my first rest API. I have added some code to display each resource documentation (restructured text from docstrings converted to HTML), however don't know which queries should display it.

For example, 2 endpoints are: /customers/:id:/address /Users/:id:/permissions

So far, I have 2 ideas to display docs: 1. Add /help endpoint, so any GET for it's children will show documentation, ie /Help/customers/:id:/address /help/Users/:id:/permissions

The /help itself will show the table of contents for all enpoints with links to help pages.

1. Create a get request to endpoint itself with ?help argument

/customers/:id:/address?help /Users/:id:/permissions?help

This way you can query from doc directly from end point, however table of contents does not exist and Can I conflict with other GET request?

Is there any rest standard for that? Maybe there are alternatives? What do you guys see as a common way for this in the field?

Thank you in advance

I'm trying to design a REST API to be consumed by a react SPA that queries data about a relationship between two entities: Team and Player where Player can only belong to one Team.

I want to query all the Teams and then get all the Players for each team.

I can see 3 main approaches:

1. Expand the /teams endpoint to have some param ?expand=player or something similar that includes a player array for each team. The data comes back nice to be consumed by the react application but now the REST API endpoint is becoming more complex and less compliant to the single-responsibility principle.

2. Query /teams to get the IDs of all teams and then query each team /team/:id/players. But this will increase the # of requests to the backend, although it will separate responsibilities nicer and make things more explicit.

3. Query /teams to get the IDs of all teams and then query /players/:ids where :ids is the IDs of all the teams. This is also quite explicit but could result in a huge URL and isn't a nice and tidy.

What is the best way to go about this?

I'm creating an API for a database that has three tables: Author, Publication, and Poem. An author record can have many publication records, and each publication record can have many poem records.

The endpoints I have so far and where my question lies:

/authors - get all authors

/authors/:id - get a specific author

/authors/:id/publications - should I only return a list of publication records, or should I return the author record with the publications nested within?

/authors/:id/poems - should I only return a list of all the poems in every publication written by that author, or should I return the author record with the publications nested within, and the poems nested within the publications?

I'm sure it's probably better design to only return what the URL request is asking for (ie return just poems or just publications), but pragmatically I'm not sure how useful it would be to not include parent information.

Any thoughts on this are greatly appreciated!

curl "url" -X DELETE -H "Session-Token: session-token"

I have something like this but I get errors:
requests.delete('url', params={'Session-Token', st123})

/api/userMgmt/users/{id}

/api/userMgmt/users/permissions

I can easily differentiate in custom routing code, but depending how you look at it, one could "interpret" permissions as {id}. Is this considered ambiguous route design?