MegaMufa

RAML (самый молодой, но рекомендую)
Swagger
Apiary

Это фреймоворки для проектировния API. По сути предоставляют свой DSL для описания и ДОКУМЕНТИРОВАНИЯ (!) API. К большинству из них идут инструменты по генерации читабельных доков и всякие mock-инструменты и генераторы клиентов-загрушек и сервисов-заглушек (для тестирования сервисов и клиентов соответственно). Вот например тулзы для Сваггера: swagger.io/swagger-codegen :

The Swagger codegen project allows generation of both client libraries and server stubs from a Swagger definition.

vREST - более комплексный продукт, включающий автоматизацию тестирования, есть платные возможности.
Mashape - большой продукт для предоставления API, используется многими крупными компаниями (напр., Близзы его юзают).

P.S. Есть еще различные модели гипермедийных API (JSON-LD, HAL, Siren, и т.д.), но это пока не очень популярные вещи, поэтому если не готовы быть одним из первопроходцев, лучше попробуйте их потом, когда наберут популярность (если наберут).

Как это работает, чтобы понимали. Я опишу истинно правильный путь, но долгий: (как подсказал pygame , по бенчмаркам https://gist.github.com/hgfischer/7965620 всё же нативный хттп сервер в Go быстрее, чем nginx с fcgi, т.к. у Go гавняная реализация fcgi, поэтому вместо fcgi быстрее будет обычный http proxy_pass).

1) Ставится веб-сервер нормальный, а не тот, который есть в самом Go. То есть, ставим nginx. Настраиваем ему все url маршруты, настраиваем отдачу статики.

2) За динамикой nginx будет обращаться к нашему Go демону. По протоколу fast-cgi. Именно по нему, потому что nginx его умеет и вообще он хорош (upd: но не в Go). Это короч бинарный протокол по которому nginx передаёт в нашу Go программу HTTP заголовки запроса от браузера и получает обратно HTTP ответ. Для этого ставим простейшую обёртку для fast-cgi под названием spawn-fcgi, она будет преднастраивать и запускать нашу Go программу, готовую для общения по протоколу fast-cgi.

3) На случай, если наша Go программа падает. Либо уже у нас есть система, которая следит за демонами и поднимает их в случае падения (systemd, upstart), тогда конфигурируем её, либо ставим таковую и тоже конфигурируем.

Привожу пример как это всё сделано у меня (самый популярный стек технологий) на Debian:

1) nginx

server {
	server_name otboi.****;
	listen 80;
	include fastcgi_params;
...
	
	location / {
		fastcgi_pass unix:/var/run/otboinik.sock;
	}

2) systemd конфиг, который стартует нашу Go программу, завёрнутую в spawn-fcgi

[Unit]
Description=Otboinik

[Service]
Restart=always
Environment=OTBOINIK_BIN=/opt/гыы/otboinik/bin/otboinik
Environment=OTBOINIK_PID=/var/run/otboinik.pid
Environment=OTBOINIK_USER=гыыыы
Environment=OTBOINIK_SOCKET=/var/run/otboinik.sock
Environment=OTBOINIK_SOCKET_USER=гыыыыы
Environment=OTBOINIK_SOCKET_MODE=0666
ExecStart=/usr/bin/spawn-fcgi -s $OTBOINIK_SOCKET -M $OTBOINIK_SOCKET_MODE -n -P $OTBOINIK_PID -u $OTBOINIK_USER -U $OTBOINIK_SOCKET_USER -G $OTBOINIK_SOCKET_USER $OTBOINIK_BIN

[Install]
WantedBy=multi-user.target

3) Сам Go код

import (
	"net/http"
	"net/http/fcgi"
)

type Server struct {
}

func (s Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
       // чиста пример
        jsonblob := r.FormValue("events")
	if jsonblob == "" {
		w.WriteHeader(http.StatusNotAcceptable)
		return
	}
}

func main() {
	server := Server{}

	func() {
		fcgi.Serve(nil, server)
	}()

	waitchan := make(chan int, 1)
	<-waitchan
}

представьте что это у вас иерархия в виде дерева каталога, сразу станет очевидно что вам необходимо указывать проджект айди.
и обычно наоборот используют - для создания пут, для обновления пост - это связанно со спецификаций, позволяющей в пост запросе отправлять не все данные объекта, в отличии от например пут, где необходимо высылать все данные объекта.

Кто-то умный написал, что программист помогает зарабатывать деньги или уменьшает издержки. Вот за это и платят.

Все понимаю - козлы, жлобы, эксплуататоры, жмоты - акционеры и руководство.
Но: хлеб у вас в магазине не дорожал? тюлька не дорожала? услуги провайдера? абонемент в спортзале? и т.д.?
Все или почти все поднялось в цене. Виноват проклятый доллар (ну, или не доллар, не важно). Поднялись и цены на бирже.

А теперь конкретно по FL. Как это работает - есть акционеры (Мажирин и аптекари) и руководство (Росошанский и Тараханов). Раз в полгода акционеры собираются и говорят руководству - уровень прибыльности должен быть такой. Аптекари покупали долю в у.е. и получать хотят у.е. Мажирину тоже у.е. нужны - хотя бы на танцы свои. Итак, в начале 2013 прибыль была 200 000 у.е. в месяц, а в начале 2015 стала 75 000 у.е. Акционеры говорят руководству - нужно вернуть хотя бы до 150 000 у.е.

Как это сделать - проблема не акционеров, а руководства. И руководство начинает действовать - вводит Profi, поднимает цену Pro, добавляет закрепления и прочие мелкие платности, увольняет кучу людей штата - почти 90%! www.the-village.ru/village/blogs/business/221897-c...
Прибыль пошла в гору. "Ф-у-у-х! Акционеры не уволят, даже премию дадут" - так думает руководство. На первом этапе это так и работает.

Но. Что имеем с итоге: сервис теряет в качестве - не хватает людей для нормального обслуживания пользователей, кода, серверов - отсюда постоянные падения, взломы и недовольство (https://vc.ru/n/fl-off, https://vc.ru/p/fl-hacked и т.д.). Сервис становится дороже (замечу - в рублях, в у.е. остается на том же уровне или дешевле) - отсюда снова недовольство пользователей.

Блин, так почему же эта биржа не умирает? Почему все снова идут и платят (судя по анализу количество PRO за последний год не уменьшилось, а только выросло)? А я скажу - потому что есть заказы. Не просто заказы, а много заказов. Смотрим сколько - primelance.com/analytics/. Блин, да столько же, сколько на всех остальных биржах вместе взятых.

Итог повествования: в обозримой перспективе ничего не изменится. На FL будет много заказов - к ней привыкли, она выделяет денег на рекламу больше остальных, только она обслуживает юриков. Поэтому туда будут идти фрилансеры, будут платить дорогой Pro. Этот самый Pro будет дальше дорожать - думаю, к середине 2016 на уровне 2000-2500 рублей. Если рубль продолжит плохо себя вести - еще больше, или переведут ценник в доллар.

Скажете, на англоязычных лучше и светлее? Нет и еще раз нет. Посмотрите ценник на том же Upwork и радуйтесь, что FL до такого еще не додумалась. Одна радость - там ценник в проектах другой, отсюда и рентабельность работы на буржуев.

Поэтому - если вы знаете или учите английский - валите по быстрому с отечественного фриланса. Если не знаете и учить не собираетесь - радуйтесь, что FL просят 1600 в месяц с неограниченным числом ответов, а не 600 за 10 ответов в месяц, и дальше по 120 рублей за каждый ответ + 10% с каждого заказа (каждого!), как это есть на Upwork.

PHP оформляйте как composer-пакеты, тогда весь проект будет собираться легко и просто. Здорово, если сумеете настроить `composer build-project` для быстрого разворачивания. Еще есть решение поверх композера для упрвления конфигами и статикой: Puli. Попробуйте его, может подойдет вам.

Клиентский код лучше продублировать скомпилированными файлами (рядом с ts положить js и по возможности min.js). Зависимости опять же через менеджер npm/bower/... Если фронтенд - отдельное приложение, то, соответственно, в отдельную репу.

Документацию (ту, что из apidoc генерится) лучше держать поближе к коду (в том же репозитории) - будет легче бороться с рассинхронизацией кода и документации. Автоматически получите документацию с привязкой к версии кода.

Для общей документации - отдельный репозиторий + github pages (хотя, возможно оформлять и через wiki-разделы)

Можно сделать отдельный репозиторий с примером приложения, где будут указаны все зависимости и присутствовать пример конфига.

А в целом, чтобы сгруппировать все это дело и удобно управлять доступом, организуйте группу на гитхабе и в ней разместите все тематические репозитории.